[Mesa-dev] [PATCH 15/16] docs: Human edits to the website code for clarity.
Laura Ekstrand
laura at jlekstrand.net
Fri May 25 00:27:18 UTC 2018
There's a lot here. If you're interested, it's mostly whitespace fixes,
switching variable names and function names to the Sphinx orange variable
highlight style, and naming code blocks to take advantage of Pygments
syntax highlighting.
---
docs/application-issues.rst | 8 +-
docs/autoconf.rst | 9 +-
docs/codingstyle.rst | 36 +++----
docs/conf.py | 2 +-
docs/conform.rst | 2 +-
docs/debugging.rst | 12 +--
docs/devinfo.rst | 26 ++---
docs/download.rst | 6 +-
docs/egl.rst | 2 +-
docs/extensions.rst | 42 ++++----
docs/faq.rst | 38 +++----
docs/helpwanted.rst | 14 +--
docs/index.rst | 240 +++++++++++++++++++++++---------------------
docs/install.rst | 64 ++++++------
docs/intro.rst | 124 +++++++++++------------
docs/license.rst | 12 +--
docs/llvmpipe.rst | 65 +++++-------
docs/mangling.rst | 4 +-
docs/meson.rst | 18 ++--
docs/osmesa.rst | 12 +--
docs/perf.rst | 85 +++++++++++-----
docs/postprocess.rst | 11 +-
docs/precompiled.rst | 6 +-
docs/release-calendar.rst | 158 ++++++++++-------------------
docs/releasing.rst | 158 ++++++++++++++---------------
docs/repository.rst | 59 ++++++-----
docs/shading.rst | 99 ++++++++++++------
docs/sourcetree.rst | 12 +--
docs/submittingpatches.rst | 123 ++++++++++++-----------
docs/thanks.rst | 2 +-
docs/versions.rst | 8 +-
docs/viewperf.rst | 94 ++++++++---------
docs/vmware-guest.rst | 146 +++++++++++++--------------
docs/xlibdriver.rst | 60 +++++------
34 files changed, 882 insertions(+), 875 deletions(-)
diff --git a/docs/application-issues.rst b/docs/application-issues.rst
index 3ab4da4fc9..7c9096875b 100644
--- a/docs/application-issues.rst
+++ b/docs/application-issues.rst
@@ -24,18 +24,18 @@ 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
+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
+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
+the ``glGetString(GL_EXTENSIONS)`` query to only report extensions older
than the given year.
For example, if the game was released in 2001, do
-::
+.. code-block:: bash
export MESA_EXTENSION_MAX_YEAR=2001
diff --git a/docs/autoconf.rst b/docs/autoconf.rst
index 25ba71cf66..d972babc6d 100644
--- a/docs/autoconf.rst
+++ b/docs/autoconf.rst
@@ -16,7 +16,7 @@ The autoconf generated configure script can be used to guess your
platform and change various options for building Mesa. To use the
configure script, type:
-::
+.. code-block:: bash
./configure
@@ -28,7 +28,7 @@ can pass them to ``autogen.sh``. It will run ``configure`` with these
options after it is generated. Once you have run ``configure`` and set
the options to your preference, type:
-::
+.. code-block:: bash
make
@@ -61,7 +61,10 @@ Some of the generic autoconf options are used with Mesa:
there's only one config file provided when dri drivers are enabled -
it's ``drirc``.
-``--enable-static, --disable-shared``
+``--enable-static``
+ .. same as below
+
+``--disable-shared``
By default, Mesa will build shared libraries. Either of these
options will force static libraries to be built. It is not currently
possible to build static and shared libraries in a single pass.
diff --git a/docs/codingstyle.rst b/docs/codingstyle.rst
index 026652f0ca..565c3ce1c9 100644
--- a/docs/codingstyle.rst
+++ b/docs/codingstyle.rst
@@ -17,7 +17,7 @@ Basic formatting guidelines
- Opening braces go on the same line as the if/for/while statement. For
example:
- ::
+ .. code-block:: c
if (condition) {
foo;
@@ -30,30 +30,30 @@ Basic formatting guidelines
- This GNU indent command generally does the right thing for
formatting:
- ::
+ .. code-block:: bash
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 <https://www.stack.nl/~dimitri/doxygen/>`__ conventions.
- | Single-line comments:
+- 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 <https://www.stack.nl/~dimitri/doxygen/>`__ conventions.
+ Single-line comments:
- ::
+ .. code-block:: c
/* null-out pointer to prevent dangling reference below */
bufferObj = NULL;
Or,
- ::
+ .. code-block:: c
bufferObj = NULL; /* prevent dangling reference below */
Multi-line comment:
- ::
+ .. code-block:: c
/* If this is a new buffer object id, or one which was generated but
* never used before, allocate a buffer object now.
@@ -61,7 +61,7 @@ Basic formatting guidelines
We try to quote the OpenGL specification where prudent:
- ::
+ .. code-block:: c
/* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
*
@@ -77,7 +77,7 @@ Basic formatting guidelines
Function comment example:
- ::
+ .. code-block:: c
/**
* Create and initialize a new buffer object. Called via the
@@ -100,7 +100,7 @@ Basic formatting guidelines
- Function names follow various conventions depending on the type of
function:
- ::
+ .. code-block:: text
glFooBar() - a public GL entry point (in glapi_dispatch.c)
_mesa_FooBar() - the internal immediate mode function
@@ -108,17 +108,17 @@ Basic formatting guidelines
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
+- 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").
+- 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.
+ ``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.
diff --git a/docs/conf.py b/docs/conf.py
index 33bf717a87..c6eac2394d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -99,7 +99,7 @@ html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['specs/']
# -- Options for HTMLHelp output ------------------------------------------
diff --git a/docs/conform.rst b/docs/conform.rst
index fad50e68f9..259d6b0a1f 100644
--- a/docs/conform.rst
+++ b/docs/conform.rst
@@ -16,7 +16,7 @@ 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.
-::
+.. code-block:: text
COVERAGE TESTS
--------------
diff --git a/docs/debugging.rst b/docs/debugging.rst
index e70a70fa6b..6bfa644f45 100644
--- a/docs/debugging.rst
+++ b/docs/debugging.rst
@@ -3,18 +3,18 @@ Debugging Tips
Normally Mesa (and OpenGL) records but does not notify the user of
errors. It is up to the application to call ``glGetError`` to check for
-errors. Mesa supports an environment variable, MESA\_DEBUG, to help with
-debugging. If MESA\_DEBUG is defined, a message will be printed to
+errors. Mesa supports an environment variable, ``MESA_DEBUG``, to help with
+debugging. If ``MESA_DEBUG`` is defined, a message will be printed to
stdout whenever an error occurs.
More extensive error checking is done when Mesa is compiled with the
DEBUG symbol defined. You'll have to edit the Make-config file and add
--DDEBUG to the CFLAGS line for your system configuration. You may also
-want to replace any optimization flags with the -g flag so you can use
-your debugger. After you've edited Make-config type 'make clean' before
+``-DDEBUG`` to the CFLAGS line for your system configuration. You may also
+want to replace any optimization flags with the ``-g`` flag so you can use
+your debugger. After you've edited Make-config type ``make clean`` before
recompiling.
-In your debugger you can set a breakpoint in \_mesa\_error() to trap
+In your debugger you can set a breakpoint in ``_mesa_error()`` to trap
Mesa errors.
There is a display list printing/debugging facility. See the end of
diff --git a/docs/devinfo.rst b/docs/devinfo.rst
index a48e94697b..d81296c863 100644
--- a/docs/devinfo.rst
+++ b/docs/devinfo.rst
@@ -8,10 +8,10 @@ Adding Extensions
To add a new GL extension to Mesa you have to do at least the following.
-- If glext.h doesn't define the extension, edit include/GL/gl.h and add
+- If ``glext.h`` doesn't define the extension, edit ``include/GL/gl.h`` and add
code like this:
- ::
+ .. code-block:: c
#ifndef GL_EXT_the_extension_name
#define GL_EXT_the_extension_name 1
@@ -19,25 +19,25 @@ To add a new GL extension to Mesa you have to do at least the following.
/* prototype the new functions */
/* TYPEDEFS for the new functions */
#endif
-
-- In the src/mapi/glapi/gen/ directory, add the new extension functions
- and enums to the gl\_API.xml file. Then, a bunch of source files must
+
+- In the ``src/mapi/glapi/gen/`` directory, add the new extension functions
+ and enums to the ``gl_API.xml`` file. Then, a bunch of source files must
be regenerated by executing the corresponding Python scripts.
-- Add a new entry to the ``gl_extensions`` struct in mtypes.h if the
+- Add a new entry to the ``gl_extensions`` struct in ``mtypes.h`` if the
extension requires driver capabilities not already exposed by another
extension.
-- Add a new entry to the src/mesa/main/extensions\_table.h file.
+- Add a new entry to the ``src/mesa/main/extensions_table.h`` file.
- From this point, the best way to proceed is to find another
extension, similar to the new one, that's already implemented in Mesa
and use it as an example.
-- If the new extension adds new GL state, the functions in get.c,
- enable.c and attrib.c will most likely require new code.
+- If the new extension adds new GL state, the functions in ``get.c``,
+ ``enable.c`` and ``attrib.c`` will most likely require new code.
- To determine if the new extension is active in the current context,
- use the auto-generated \_mesa\_has\_##name\_str() function defined in
- src/mesa/main/extensions.h.
-- The dispatch tests check\_table.cpp and dispatch\_sanity.cpp should
+ use the auto-generated ``_mesa_has_##name_str()`` function defined in
+ ``src/mesa/main/extensions.h``.
+- The dispatch tests ``check_table.cpp`` and ``dispatch_sanity.cpp`` should
be updated with details about the new extensions functions. These
- tests are run using 'make check'
+ tests are run using ``make check``
diff --git a/docs/download.rst b/docs/download.rst
index a71f3b5cac..e64789ba98 100644
--- a/docs/download.rst
+++ b/docs/download.rst
@@ -23,13 +23,13 @@ Mesa releases are available in two formats: ``.tar.xz`` and ``.tar.gz``.
To unpack the tarball:
-::
+.. code-block:: bash
tar xf mesa-Y.N.P.tar.xz
or
-::
+.. code-block:: bash
tar xf mesa-Y.N.P.tar.gz
@@ -38,7 +38,7 @@ Contents
After unpacking you'll have these files and directories (among others):
-::
+.. code-block:: text
autogen.sh - Autoconf script for *nix systems
scons/ - SCons script for Windows builds
diff --git a/docs/egl.rst b/docs/egl.rst
index 58caf945e9..043571abc2 100644
--- a/docs/egl.rst
+++ b/docs/egl.rst
@@ -18,7 +18,7 @@ Build EGL
#. Run ``configure`` with the desired client APIs and enable the driver
for your hardware. For example
- ::
+ .. code-block:: bash
$ ./configure --enable-gles1 --enable-gles2 \
--with-dri-drivers=... \
diff --git a/docs/extensions.rst b/docs/extensions.rst
index 7289f337a4..a202880fce 100644
--- a/docs/extensions.rst
+++ b/docs/extensions.rst
@@ -4,28 +4,28 @@ Mesa Extensions
A number of extensions have been developed especially for Mesa. The
specifications follow.
-- `MESA\_agp\_offset.spec <specs/OLD/MESA_agp_offset.spec>`__
-- `MESA\_copy\_sub\_buffer.spec <specs/MESA_copy_sub_buffer.spec>`__
-- `MESA\_drm\_image.spec <specs/MESA_drm_image.spec>`__
-- `MESA\_multithread\_makecurrent.spec <specs/MESA_multithread_makecurrent.spec>`__
-- `MESA\_packed\_depth\_stencil.spec <specs/OLD/MESA_packed_depth_stencil.spec>`__
+- `MESA\_agp\_offset.spec <_static/OLD/MESA_agp_offset.spec>`__
+- `MESA\_copy\_sub\_buffer.spec <_static/MESA_copy_sub_buffer.spec>`__
+- `MESA\_drm\_image.spec <_static/MESA_drm_image.spec>`__
+- `MESA\_multithread\_makecurrent.spec <_static/MESA_multithread_makecurrent.spec>`__
+- `MESA\_packed\_depth\_stencil.spec <_static/OLD/MESA_packed_depth_stencil.spec>`__
(obsolete)
-- `MESA\_pack\_invert.spec <specs/MESA_pack_invert.spec>`__
-- `MESA\_pixmap\_colormap.spec <specs/MESA_pixmap_colormap.spec>`__
-- `MESA\_program\_debug.spec <specs/OLD/MESA_program_debug.spec>`__
+- `MESA\_pack\_invert.spec <_static/MESA_pack_invert.spec>`__
+- `MESA\_pixmap\_colormap.spec <_static/MESA_pixmap_colormap.spec>`__
+- `MESA\_program\_debug.spec <_static/OLD/MESA_program_debug.spec>`__
(obsolete)
-- `MESA\_release\_buffers.spec <specs/MESA_release_buffers.spec>`__
-- `MESA\_resize\_buffers.spec <specs/OLD/MESA_resize_buffers.spec>`__
+- `MESA\_release\_buffers.spec <_static/MESA_release_buffers.spec>`__
+- `MESA\_resize\_buffers.spec <_static/OLD/MESA_resize_buffers.spec>`__
(obsolete)
-- `MESA\_set\_3dfx\_mode.spec <specs/OLD/MESA_set_3dfx_mode.spec>`__
-- `MESA\_shader\_debug.spec <specs/MESA_shader_debug.spec>`__
-- `MESA\_sprite\_point.spec <specs/OLD/MESA_sprite_point.spec>`__
+- `MESA\_set\_3dfx\_mode.spec <_static/OLD/MESA_set_3dfx_mode.spec>`__
+- `MESA\_shader\_debug.spec <_static/MESA_shader_debug.spec>`__
+- `MESA\_sprite\_point.spec <_static/OLD/MESA_sprite_point.spec>`__
(obsolete)
-- `MESA\_swap\_control.spec <specs/MESA_swap_control.spec>`__
-- `MESA\_swap\_frame\_usage.spec <specs/MESA_swap_frame_usage.spec>`__
-- `MESA\_texture\_array.spec <specs/MESA_texture_array.spec>`__
-- `MESA\_texture\_signed\_rgba.spec <specs/MESA_texture_signed_rgba.spec>`__
-- `MESA\_trace.spec <specs/OLD/MESA_trace.spec>`__ (obsolete)
-- `MESA\_window\_pos.spec <specs/MESA_window_pos.spec>`__
-- `MESA\_ycbcr\_texture.spec <specs/MESA_ycbcr_texture.spec>`__
-- `WL\_bind\_wayland\_display.spec <specs/WL_bind_wayland_display.spec>`__
+- `MESA\_swap\_control.spec <_static/MESA_swap_control.spec>`__
+- `MESA\_swap\_frame\_usage.spec <_static/MESA_swap_frame_usage.spec>`__
+- `MESA\_texture\_array.spec <_static/MESA_texture_array.spec>`__
+- `MESA\_texture\_signed\_rgba.spec <_static/MESA_texture_signed_rgba.spec>`__
+- `MESA\_trace.spec <_static/OLD/MESA_trace.spec>`__ (obsolete)
+- `MESA\_window\_pos.spec <_static/MESA_window_pos.spec>`__
+- `MESA\_ycbcr\_texture.spec <_static/MESA_ycbcr_texture.spec>`__
+- `WL\_bind\_wayland\_display.spec <_static/WL_bind_wayland_display.spec>`__
diff --git a/docs/faq.rst b/docs/faq.rst
index 543ef548b6..bcb552cc95 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -3,15 +3,14 @@ Mesa Frequently Asked Questions
Last updated: 9 October 2012
-|
Index
------
+=====
-| `1. High-level Questions and Answers <#part1>`__
-| `2. Compilation and Installation Problems <#part2>`__
-| `3. Runtime / Rendering Problems <#part3>`__
-| `4. Developer Questions <#part4>`__
+ 1. `High-level Questions and Answers <#part1>`__
+ 2. `Compilation and Installation Problems <#part2>`__
+ 3. `Runtime / Rendering Problems <#part3>`__
+ 4. `Developer Questions <#part4>`__
1. High-level Questions and Answers
===================================
@@ -127,7 +126,6 @@ is an OpenGL subset library for TI graphing calculators.
There may be other open OpenGL implementations, but Mesa is the most
popular and feature-complete.
-|
2. Compilation and Installation Problems
========================================
@@ -194,8 +192,6 @@ Mesa with
``./configure --prefix=/usr --libdir=xxx --with-dri-driverdir=xxx`` and
then install with ``sudo make install``.
-|
-
3. Runtime / Rendering Problems
===============================
@@ -227,40 +223,38 @@ for details.
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 `` glXChooseVisual`` in your code.
+you can modify the parameters to ``glXChooseVisual`` in your code.
3.3 Why Isn't depth buffering working at all?
---------------------------------------------
Be sure you're requesting a depth buffered-visual. If you set the
-MESA\_DEBUG environment variable it will warn you about trying to enable
+``MESA_DEBUG`` environment variable it will warn you about trying to enable
depth testing when you don't have a depth buffer.
Specifically, make sure ``glutInitDisplayMode`` is being called with
``GLUT_DEPTH`` or ``glXChooseVisual`` is being called with a non-zero
-value for GLX\_DEPTH\_SIZE.
+value for ``GLX_DEPTH_SIZE``.
This discussion applies to stencil buffers, accumulation buffers and
alpha channels too.
-3.4 Why does glGetString() always return NULL?
-----------------------------------------------
+3.4 Why does ``glGetString()`` always return NULL?
+--------------------------------------------------
Be sure you have an active/current OpenGL rendering context before
-calling glGetString.
+calling ``glGetString``.
-3.5 GL\_POINTS and GL\_LINES don't touch the right pixels
----------------------------------------------------------
+3.5 ``GL_POINTS`` and ``GL_LINES`` don't touch the right pixels
+---------------------------------------------------------------
-If you're trying to draw a filled region by using GL\_POINTS or
-GL\_LINES and seeing holes or gaps it's because of a float-to-int
+If you're trying to draw a filled region by using ``GL_POINTS`` or
+``GL_LINES`` 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.
-|
-
4. Developer Questions
======================
@@ -297,7 +291,7 @@ being said, many people have managed to figure out the process.
Joining the appropriate mailing lists and asking questions (and
searching the archives) is a good way to get information.
-4.3 Why isn't GL\_EXT\_texture\_compression\_s3tc implemented in Mesa?
+4.3 Why isn't ``GL_EXT_texture_compression_s3tc`` implemented in Mesa?
----------------------------------------------------------------------
The `specification for the
diff --git a/docs/helpwanted.rst b/docs/helpwanted.rst
index 8d426474a4..15ee1a6478 100644
--- a/docs/helpwanted.rst
+++ b/docs/helpwanted.rst
@@ -12,23 +12,23 @@ specific ideas and areas where help would be appreciated:
helpful.
#. **Driver debugging.** There are plenty of open bugs in the `bug
database <https://bugs.freedesktop.org/describecomponents.cgi?product=Mesa>`__.
-#. **Remove aliasing warnings.** Enable gcc -Wstrict-aliasing=2
- -fstrict-aliasing and track down aliasing issues in the code.
-#. **Contribute more tests to
- `Piglit <https://piglit.freedesktop.org/>`__.**
+#. **Remove aliasing warnings.** Enable ``gcc -Wstrict-aliasing=2
+ -fstrict-aliasing`` and track down aliasing issues in the code.
+#. **Contribute more tests to**
+ `Piglit <https://piglit.freedesktop.org/>`__.
You can find some further To-do lists here:
**Common To-Do lists:**
-- `**features.txt** <https://cgit.freedesktop.org/mesa/mesa/tree/docs/features.txt>`__
+- `features.txt <https://cgit.freedesktop.org/mesa/mesa/tree/docs/features.txt>`__
- Status of OpenGL 3.x / 4.x features in Mesa.
**Legacy Driver specific To-Do lists:**
-- `**r600g** <https://dri.freedesktop.org/wiki/R600ToDo>`__ - Driver
+- `r600g <https://dri.freedesktop.org/wiki/R600ToDo>`__ - Driver
for ATI/AMD R600 - Northern Island.
-- `**r300g** <https://dri.freedesktop.org/wiki/R300ToDo>`__ - Driver
+- `r300g <https://dri.freedesktop.org/wiki/R300ToDo>`__ - Driver
for ATI R300 - R500.
If you want to do something new in Mesa, first join the Mesa developer's
diff --git a/docs/index.rst b/docs/index.rst
index 08553e8562..df4843f04b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -118,11 +118,12 @@ release.
April 18, 2018
--------------
-| `Mesa 17.3.9 <relnotes/17.3.9.html>`__ is released. This is a bug-fix
- release.
-| NOTE: It is anticipated that 17.3.9 will be the final release in the
- 17.3 series. Users of 17.3 are encouraged to migrate to the 18.0
- series in order to obtain future fixes.
+`Mesa 17.3.9 <relnotes/17.3.9.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: It is anticipated that 17.3.9 will be the final release in the
+ 17.3 series. Users of 17.3 are encouraged to migrate to the 18.0
+ series in order to obtain future fixes.
April 03, 2018
--------------
@@ -176,11 +177,12 @@ release.
December 22, 2017
-----------------
-| `Mesa 17.2.8 <relnotes/17.2.8.html>`__ is released. This is a bug-fix
- release.
-| NOTE: It is anticipated that 17.2.8 will be the final release in the
- 17.2 series. Users of 17.2 are encouraged to migrate to the 17.3
- series in order to obtain future fixes.
+`Mesa 17.2.8 <relnotes/17.2.8.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: It is anticipated that 17.2.8 will be the final release in the
+ 17.2 series. Users of 17.2 are encouraged to migrate to the 17.3
+ series in order to obtain future fixes.
December 21, 2017
-----------------
@@ -234,11 +236,12 @@ release.
September 25, 2017
------------------
-| `Mesa 17.1.10 <relnotes/17.1.10.html>`__ is released. This is a
- bug-fix release.
-| NOTE: It is anticipated that 17.1.10 will be the final release in the
- 17.1 series. Users of 17.1 are encouraged to migrate to the 17.2
- series in order to obtain future fixes.
+`Mesa 17.1.10 <relnotes/17.1.10.html>`__ is released. This is a
+bug-fix release.
+
+ NOTE: It is anticipated that 17.1.10 will be the final release in the
+ 17.1 series. Users of 17.1 are encouraged to migrate to the 17.2
+ series in order to obtain future fixes.
September 17, 2017
------------------
@@ -304,11 +307,12 @@ release.
June 1, 2017
------------
-| `Mesa 17.0.7 <relnotes/17.0.7.html>`__ is released. This is a bug-fix
- release.
-| NOTE: It is anticipated that 17.0.7 will be the final release in the
- 17.0 series. Users of 17.0 are encouraged to migrate to the 17.1
- series in order to obtain future fixes.
+`Mesa 17.0.7 <relnotes/17.0.7.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: It is anticipated that 17.0.7 will be the final release in the
+ 17.0 series. Users of 17.0 are encouraged to migrate to the 17.1
+ series in order to obtain future fixes.
May 25, 2017
------------
@@ -350,12 +354,13 @@ release.
March 20, 2017
--------------
-| `Mesa 13.0.6 <relnotes/13.0.6.html>`__ and `Mesa
- 17.0.2 <relnotes/17.0.2.html>`__ are released. These are bug-fix
- releases from the 13.0 and 17.0 branches, respectively.
-| NOTE: It is anticipated that 13.0.6 will be the final release in the
- 13.0 series. Users of 13.0 are encouraged to migrate to the 17.0
- series in order to obtain future fixes.
+`Mesa 13.0.6 <relnotes/13.0.6.html>`__ and `Mesa
+17.0.2 <relnotes/17.0.2.html>`__ are released. These are bug-fix
+releases from the 13.0 and 17.0 branches, respectively.
+
+ NOTE: It is anticipated that 13.0.6 will be the final release in the
+ 13.0 series. Users of 13.0 are encouraged to migrate to the 17.0
+ series in order to obtain future fixes.
March 4, 2017
-------------
@@ -385,12 +390,13 @@ release.
January 23, 2017
----------------
-| `Mesa 12.0.6 <relnotes/12.0.6.html>`__ is released. This is a bug-fix
- release.
-| NOTE: This is an extra release for the 12.0 stable branch, as per
- developers' feedback. It is anticipated that 12.0.6 will be the final
- release in the 12.0 series. Users of 12.0 are encouraged to migrate to
- the 13.0 series in order to obtain future fixes.
+`Mesa 12.0.6 <relnotes/12.0.6.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: This is an extra release for the 12.0 stable branch, as per
+ developers' feedback. It is anticipated that 12.0.6 will be the final
+ release in the 12.0 series. Users of 12.0 are encouraged to migrate to
+ the 13.0 series in order to obtain future fixes.
January 5, 2017
---------------
@@ -401,11 +407,12 @@ release.
December 5, 2016
----------------
-| `Mesa 12.0.5 <relnotes/12.0.5.html>`__ is released. This is a bug-fix
- release.
-| NOTE: It is anticipated that 12.0.5 will be the final release in the
- 12.0 series. Users of 12.0 are encouraged to migrate to the 13.0
- series in order to obtain future fixes.
+`Mesa 12.0.5 <relnotes/12.0.5.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: It is anticipated that 12.0.5 will be the final release in the
+ 12.0 series. Users of 12.0 are encouraged to migrate to the 13.0
+ series in order to obtain future fixes.
November 28, 2016
-----------------
@@ -457,12 +464,13 @@ the release.
May 9, 2016
-----------
-| `Mesa 11.1.4 <relnotes/11.1.4.html>`__ and `Mesa
- 11.2.2 <relnotes/11.2.2.html>`__ are released. These are bug-fix
- releases from the 11.1 and 11.2 branches, respectively.
-| NOTE: It is anticipated that 11.1.4 will be the final release in the
- 11.1.4 series. Users of 11.1 are encouraged to migrate to the 11.2
- series in order to obtain future fixes.
+`Mesa 11.1.4 <relnotes/11.1.4.html>`__ and `Mesa
+11.2.2 <relnotes/11.2.2.html>`__ are released. These are bug-fix
+releases from the 11.1 and 11.2 branches, respectively.
+
+ NOTE: It is anticipated that 11.1.4 will be the final release in the
+ 11.1.4 series. Users of 11.1 are encouraged to migrate to the 11.2
+ series in order to obtain future fixes.
April 17, 2016
--------------
@@ -487,11 +495,12 @@ release.
January 22, 2016
----------------
-| `Mesa 11.0.9 <relnotes/11.0.9.html>`__ is released. This is a bug-fix
- release.
-| NOTE: It is anticipated that 11.0.9 will be the final release in the
- 11.0 series. Users of 11.0 are encouraged to migrate to the 11.1
- series in order to obtain future fixes.
+`Mesa 11.0.9 <relnotes/11.0.9.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: It is anticipated that 11.0.9 will be the final release in the
+ 11.0 series. Users of 11.0 are encouraged to migrate to the 11.1
+ series in order to obtain future fixes.
January 13, 2016
----------------
@@ -550,11 +559,12 @@ release.
October 3, 2015
---------------
-| `Mesa 10.6.9 <relnotes/10.6.9.html>`__ is released. This is a bug-fix
- release.
-| NOTE: It is anticipated that 10.6.9 will be the final release in the
- 10.6 series. Users of 10.6 are encouraged to migrate to the 11.0
- series in order to obtain future fixes.
+`Mesa 10.6.9 <relnotes/10.6.9.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: It is anticipated that 10.6.9 will be the final release in the
+ 10.6 series. Users of 10.6 are encouraged to migrate to the 11.0
+ series in order to obtain future fixes.
September 28, 2015
------------------
@@ -620,11 +630,12 @@ release.
July 04, 2015
-------------
-| `Mesa 10.5.9 <relnotes/10.5.9.html>`__ is released. This is a bug-fix
- release.
-| NOTE: It is anticipated that 10.5.9 will be the final release in the
- 10.5 series. Users of 10.5 are encouraged to migrate to the 10.6
- series in order to obtain future fixes.
+`Mesa 10.5.9 <relnotes/10.5.9.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: It is anticipated that 10.5.9 will be the final release in the
+ 10.5 series. Users of 10.5 are encouraged to migrate to the 10.6
+ series in order to obtain future fixes.
June 29, 2015
-------------
@@ -727,12 +738,13 @@ release.
January 12, 2015
----------------
-| `Mesa 10.3.7 <relnotes/10.3.7.html>`__ and `Mesa
- 10.4.2 <relnotes/10.4.2.html>`__ are released. These are bug-fix
- releases from the 10.3 and 10.4 branches, respectively.
-| NOTE: It is anticipated that 10.3.7 will be the final release in the
- 10.3 series. Users of 10.3 are encouraged to migrate to the 10.4
- series in order to obtain future fixes.
+`Mesa 10.3.7 <relnotes/10.3.7.html>`__ and `Mesa
+10.4.2 <relnotes/10.4.2.html>`__ are released. These are bug-fix
+releases from the 10.3 and 10.4 branches, respectively.
+
+ NOTE: It is anticipated that 10.3.7 will be the final release in the
+ 10.3 series. Users of 10.3 are encouraged to migrate to the 10.4
+ series in order to obtain future fixes.
December 29, 2014
-----------------
@@ -775,12 +787,13 @@ release.
October 12, 2014
----------------
-| `Mesa 10.2.9 <relnotes/10.2.9.html>`__ and `Mesa
- 10.3.1 <relnotes/10.3.1.html>`__ are released. These are bug-fix
- releases from the 10.2 and 10.3 branches, respectively.
-| NOTE: It is anticipated that 10.2.9 will be the final release in the
- 10.2 series. Users of 10.2 are encouraged to migrate to the 10.3
- series in order to obtain future fixes.
+`Mesa 10.2.9 <relnotes/10.2.9.html>`__ and `Mesa
+10.3.1 <relnotes/10.3.1.html>`__ are released. These are bug-fix
+releases from the 10.2 and 10.3 branches, respectively.
+
+ NOTE: It is anticipated that 10.2.9 will be the final release in the
+ 10.2 series. Users of 10.2 are encouraged to migrate to the 10.3
+ series in order to obtain future fixes.
September 19, 2014
------------------
@@ -883,12 +896,13 @@ release.
April 18, 2014
--------------
-| `Mesa 10.0.5 <relnotes/10.0.5.html>`__ is released. This is a bug-fix
- release.
-| NOTE: Since the 10.1.1 release is being released concurrently, it is
- anticipated that 10.0.5 will be the final release in the 10.0 series.
- Users of 10.0 are encouraged to migrate to the 10.1 series in order to
- obtain future fixes.
+`Mesa 10.0.5 <relnotes/10.0.5.html>`__ is released. This is a bug-fix
+release.
+
+ NOTE: Since the 10.1.1 release is being released concurrently, it is
+ anticipated that 10.0.5 will be the final release in the 10.0 series.
+ Users of 10.0 are encouraged to migrate to the 10.1 series in order to
+ obtain future fixes.
March 12, 2014
--------------
@@ -1348,7 +1362,7 @@ version 6.3.1.
The MD5 checksums are:
-::
+.. code-block:: bash
98192e45ed8d69113688f89f90869346 MesaLib-6.3.2.tar.gz
0df27701df0924d17ddf41185efa8ce1 MesaLib-6.3.2.tar.bz2
@@ -1363,7 +1377,7 @@ July 20, 2005
Mesa 6.3 has been released. This is a development release with new
features, changes and bug fixes.
-::
+.. code-block:: text
New:
- GL_EXT_framebuffer_object extension
@@ -1402,7 +1416,7 @@ features, changes and bug fixes.
The MD5 checksums are:
-::
+.. code-block:: bash
0236f552d37514776945d5a013e5bb7b MesaLib-6.3.tar.gz
60e1a8f78c4a8c7750a1e95753190986 MesaLib-6.3.tar.bz2
@@ -1417,7 +1431,7 @@ December 9, 2004
Mesa 6.2.1 has been released. This is a stable release which just fixes
bugs since the 6.2 release.
-::
+.. code-block:: text
Bug fixes:
- don't apply regular fog or color sum when using a fragment program
@@ -1436,7 +1450,7 @@ bugs since the 6.2 release.
The MD5 checksums are:
-::
+.. code-block:: bash
80008a92f6e055d3bfdde2cf331ec3fa MesaLib-6.2.1.tar.gz
f43228cd2bf70f583ef3275c1c545421 MesaLib-6.2.1.tar.bz2
@@ -1451,7 +1465,7 @@ October 2, 2004
Mesa 6.2 has been released. This is a stable release which just fixes
bugs since the 6.1 release.
-::
+.. code-block:: text
New:
- enabled GL_ARB_texture_rectangle (same as GL_NV_texture_rectangle)
@@ -1474,7 +1488,7 @@ bugs since the 6.1 release.
The MD5 checksums are:
-::
+.. code-block:: bash
9e8f34b059272dbb8e1f2c968b33bbf0 MesaLib-6.2.tar.gz
3d6a6362390b6a37d3cb2e615f3ac7db MesaLib-6.2.tar.bz2
@@ -1489,7 +1503,7 @@ August 18, 2004
Mesa 6.1 has been released. This is a new development release (version
6.2 will be a stabilization release).
-::
+.. code-block:: text
New:
- Revamped Makefile system
@@ -1528,7 +1542,7 @@ Mesa 6.1 has been released. This is a new development release (version
The MD5 checksums are:
-::
+.. code-block:: bash
c9284d295ebcd2e0486cc3cd54e5863c MesaLib-6.1.tar.gz
5de1f53ec0709f60fc68fdfed57351f3 MesaLib-6.1.tar.bz2
@@ -1543,7 +1557,7 @@ April 2, 2004
Mesa 6.0.1 has been released. This release basically just fixes bugs
since the 6.0. release.
-::
+.. code-block:: text
New:
- upgraded glext.h to version 22
@@ -1578,7 +1592,7 @@ since the 6.0. release.
The MD5 checksums are:
-::
+.. code-block:: bash
011be0e79666c7a6eb9693fbf9348653 MesaLib-6.0.1.tar.gz
b7f14088c5c2f14490d2739a91102112 MesaLib-6.0.1.tar.bz2
@@ -1593,7 +1607,7 @@ January 16, 2004
Mesa 6.0 has been released. This is a stabilization of the 5.1 release
and primarily just incorporates bug fixes.
-::
+.. code-block:: text
New:
- full OpenGL 1.5 support
@@ -1626,7 +1640,7 @@ Mesa 5.1 has been released. This is a new development release. Mesa 6.0
will be the next stable release and will support all OpenGL 1.5
features.
-::
+.. code-block:: text
New features:
- reorganized directory tree
@@ -1668,7 +1682,7 @@ features.
The MD5 checksums are:
-::
+.. code-block:: bash
78f452f6c55478471a744f07147612b5 MesaLib-5.1.tar.gz
67b3b8d3f7f4c8c44904551b851d01af MesaLib-5.1.tar.bz2
@@ -1685,7 +1699,7 @@ number of automake/libtool problems.
The new MD5 checksums are:
-::
+.. code-block:: bash
a9dcf3ff9ad1b7d6ce73a0df7cff8b5b MesaLib-5.0.2.tar.gz
7b4bf9261657c2fca03796d4955e6f50 MesaLib-5.0.2.tar.bz2
@@ -1699,7 +1713,7 @@ September 5, 2003
Mesa 5.0.2 has been released. This is a stable, bug-fix release.
-::
+.. code-block:: text
Bug fixes:
- fixed texgen problem causing texcoord's Q to be zero (stex3d)
@@ -1742,7 +1756,7 @@ March 30, 2003
Mesa 5.0.1 has been released. This is a stable, bug-fix release.
-::
+.. code-block:: text
New:
- DOS driver updates from Daniel Borca
@@ -1781,7 +1795,7 @@ Mesa 5.0.1 has been released. This is a stable, bug-fix release.
MD5 checksums follow:
-::
+.. code-block:: bash
b80f8b5d53a3e9f19b9fde5af0c542f0 MesaLib-5.0.1.tar.gz
513b4bbd7d38951f05027179063d876b MesaLib-5.0.1.tar.bz2
@@ -1806,7 +1820,7 @@ November 13, 2002
Mesa 5.0 has been released. This is a stable release which implements
the OpenGL 1.4 specification.
-::
+.. code-block:: text
New:
- OpenGL 1.4 support (glGetString(GL_VERSION) returns "1.4")
@@ -1836,7 +1850,7 @@ October 29, 2002
Mesa 4.1 has been released. This is a new development release. For a
stable release, get 4.0.4.
-::
+.. code-block:: text
New:
- GL_NV_vertex_program extension
@@ -1893,7 +1907,7 @@ October 3, 2002
Mesa 4.0.4 has been released. This is a stable bug-fix release.
-::
+.. code-block:: text
New:
- GL_NV_texture_rectangle extension
@@ -1927,7 +1941,7 @@ June 25, 2002
Mesa 4.0.3 has been released. This is a stable bug-fix release.
-::
+.. code-block:: text
New:
- updated GL/glext.h file (version 15)
@@ -1960,7 +1974,7 @@ April 2, 2002
Mesa 4.0.2 has been released. This is a stable bug-fix release.
-::
+.. code-block:: text
New:
- New DOS (DJGPP) driver written by Daniel Borca
@@ -1990,7 +2004,7 @@ December 17, 2001
Mesa 4.0.1 has been released. This is a stable bug-fix release.
-::
+.. code-block:: text
New:
- better sub-pixel sample positions for AA triangles (Ray Tice)
@@ -2023,7 +2037,7 @@ October 22, 2001
Mesa 4.0 has been released. This is a stable release.
-::
+.. code-block:: text
New:
- Mesa 4.0 implements the OpenGL 1.3 specification
@@ -2058,7 +2072,7 @@ June 21, 2001
Mesa 3.5 has been released. This is a new development release.
-::
+.. code-block:: text
New:
- internals of Mesa divided into modular pieces (Keith Whitwell)
@@ -2103,7 +2117,7 @@ May 17, 2001
Mesa 3.4.2 has been released. This is basically just a bug-fix release.
Here's what's new:
-::
+.. code-block:: text
Bug fixes:
- deleting the currently bound texture could cause bad problems
@@ -2131,15 +2145,15 @@ April 29, 2001
New Mesa website
-| Mark Manning produced the new website.
-| Thanks, Mark!
+ Mark Manning produced the new website.
+ Thanks, Mark!
February 14, 2001
-----------------
Mesa 3.4.1 has been released. Here's what's new:
-::
+.. code-block:: text
New:
- fixed some Linux build problems
@@ -2171,7 +2185,7 @@ November 3, 2000
Mesa 3.4 has been released. Here's what's new since the 3.3 release:
-::
+.. code-block:: text
New:
- optimized glDrawPixels for glPixelZoom(1,-1)
@@ -2204,7 +2218,7 @@ April 24, 2000
Mesa 3.2 has been released. Here's what's new since the beta release:
-::
+.. code-block:: text
Bug fixes:
- fixed memcpy bugs in span.c
@@ -2230,7 +2244,7 @@ it's mainly just bug fixes.
Here's what's changed:
-::
+.. code-block:: text
Bug fixes:
- mixed drawing of lines and bitmaps sometimes had wrong colors
@@ -2267,9 +2281,9 @@ Here's what's changed:
Changes:
- glXCopyContext's mask parameter is now unsigned long, per GLX spec
-| Please report any problems with this release ASAP. Bugs should be
- filed on the Mesa3D website at sourceforge.
-| After 3.2 is wrapped up I hope to release 3.3 beta 1 soon afterward.
+ Please report any problems with this release ASAP. Bugs should be
+ filed on the Mesa3D website at sourceforge.
+ After 3.2 is wrapped up I hope to release 3.3 beta 1 soon afterward.
-- Brian
@@ -2370,7 +2384,7 @@ Precision Insight has posted their lowlevel design documents at
May 13, 1999
------------
-::
+.. code-block:: text
May 1999 - John Carmack of id Software, Inc. has made a donation of
US$10,000 to the Mesa project to support its continuing development.
diff --git a/docs/install.rst b/docs/install.rst
index 177e393d56..0fe6773e61 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -41,10 +41,11 @@ you're willing to maintain support for other compiler get in touch.
- Microsoft Visual Studio 2013 Update 4 or later is required, for
building on Windows.
-| Third party/extra tools.
-| **Note**: These should not be required, when building from a release
- tarball. If you think you've spotted a bug let developers know by
- filing a `bug report <bugs.html>`__.
+Third party/extra tools.
+
+**Note**: These should not be required, when building from a release
+tarball. If you think you've spotted a bug let developers know by
+filing a `bug report <bugs.html>`__.
- `Python <https://www.python.org/>`__ - Python is required. Version
2.6.4 or later should work.
@@ -52,26 +53,19 @@ you're willing to maintain support for other compiler get in touch.
module is required. Version 0.3.4 or later should work.
- lex / yacc - for building the Mesa IR and GLSL compiler.
- .. raw:: html
-
- <div>
-
On Linux systems, flex and bison versions 2.5.35 and 2.4.1,
respectively, (or later) should work. On Windows with MinGW, install
flex and bison with:
- ::
+
+ .. code-block:: bash
mingw-get install msys-flex msys-bison
For MSVC on Windows, install `Win
flex-bison <http://winflexbison.sourceforge.net/>`__.
- .. raw:: html
-
- </div>
-
-**Note**: Some versions can be buggy (eg. flex 2.6.2) so do try others
-if things fail.
+ **Note**: Some versions can be buggy (eg. flex 2.6.2) so do try others
+ if things fail.
1.2 Requirements
~~~~~~~~~~~~~~~~
@@ -83,7 +77,7 @@ error message.
Here are some common ways to retrieve most/all of the dependencies based
on the packaging tool used by your distro.
-::
+.. code-block:: bash
zypper source-install --build-deps-only Mesa # openSUSE/SLED/SLES
yum-builddep mesa # yum Fedora, OpenSuse(?)
@@ -98,7 +92,7 @@ The primary method to build Mesa on Unix systems is with autoconf.
The general approach is the standard:
-::
+.. code-block:: bash
./configure
make
@@ -112,25 +106,25 @@ for more details.
To build Mesa with SCons on Linux or Windows do
-::
+.. code-block:: bash
scons
The build output will be placed in
-build/\ *platform*-*machine*-*debug*/..., where *platform* is for
-example linux or windows, *machine* is x86 or x86\_64, optionally
-followed by -debug for debug builds.
+``build/platform-machine-debug/...``, where ``platform`` is for
+example linux or windows, ``machine`` is ``x86`` or ``x86_64``, optionally
+followed by ``-debug`` for debug builds.
To build Mesa with SCons for Windows on Linux using the MinGW
crosscompiler toolchain do
-::
+.. code-block:: bash
scons platform=windows toolchain=crossmingw machine=x86 libgl-gdi
This will create:
-- build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll — Mesa
+- ``build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll`` — Mesa
+ Gallium + softpipe (or llvmpipe), binary compatible with Windows's
opengl32.dll
@@ -144,11 +138,11 @@ Currently one can build Mesa for Android as part of the AOSP project,
yet your experience might vary.
In order to achieve that one should update their local manifest to point
-to the upstream repo, set the appropriate BOARD\_GPU\_DRIVERS and build
-the libGLES\_mesa library.
+to the upstream repo, set the appropriate ``BOARD_GPU_DRIVERS`` and build
+the ``libGLES_mesa`` library.
-FINISHME: Improve on the instructions add references to Rob H
-repos/Jenkins, Android-x86 and/or other resources.
+ *FINISHME*: Improve on the instructions add references to Rob H
+ repos/Jenkins, Android-x86 and/or other resources.
5. Library Information
======================
@@ -157,7 +151,7 @@ When compilation has finished, look in the top-level ``lib/`` (or
``lib64/``) directory. You'll see a set of library files similar to
this:
-::
+.. code-block:: bash
lrwxrwxrwx 1 brian users 10 Mar 26 07:53 libGL.so -> libGL.so.1*
lrwxrwxrwx 1 brian users 19 Mar 26 07:53 libGL.so.1 -> libGL.so.1.5.060100*
@@ -166,12 +160,13 @@ this:
lrwxrwxrwx 1 brian users 23 Mar 26 07:53 libOSMesa.so.6 -> libOSMesa.so.6.1.060100*
-rwxr-xr-x 1 brian users 23871 Mar 26 07:53 libOSMesa.so.6.1.060100*
-| **libGL** is the main OpenGL library (i.e. Mesa).
-| **libOSMesa** is the OSMesa (Off-Screen) interface library.
+**libGL** is the main OpenGL library (i.e. Mesa).
+
+**libOSMesa** is the OSMesa (Off-Screen) interface library.
If you built the DRI hardware drivers, you'll also see the DRI drivers:
-::
+.. code-block:: bash
-rwxr-xr-x 1 brian users 16895413 Jul 21 12:11 i915_dri.so
-rwxr-xr-x 1 brian users 16895413 Jul 21 12:11 i965_dri.so
@@ -185,15 +180,14 @@ Gallium-based versions of libGL and device drivers.
===========================================
Running ``make install`` will install package configuration files for
-the pkg-config utility.
+the ``pkg-config`` utility.
-When compiling your OpenGL application you can use pkg-config to
+When compiling your OpenGL application you can use ``pkg-config`` to
determine the proper compiler and linker flags.
For example, compiling and linking a GLUT application can be done with:
-::
+.. code-block:: bash
gcc `pkg-config --cflags --libs glut` mydemo.c -o mydemo
-|
diff --git a/docs/intro.rst b/docs/intro.rst
index a85a257fc8..62fcc5abe2 100644
--- a/docs/intro.rst
+++ b/docs/intro.rst
@@ -153,8 +153,8 @@ Version 9.x of Mesa implements the OpenGL 3.1 API. While the driver for
Intel Sandy Bridge and Ivy Bridge is the only driver to support OpenGL
3.1, many developers across the open-source community contributed
features required for OpenGL 3.1. The primary features added since the
-Mesa 8.0 release are GL\_ARB\_texture\_buffer\_object and
-GL\_ARB\_uniform\_buffer\_object.
+Mesa 8.0 release are ``GL_ARB_texture_buffer_object`` and
+``GL_ARB_uniform_buffer_object``.
Version 9.0 of Mesa also included the first release of the Clover state
tracker for OpenCL.
@@ -178,14 +178,14 @@ Version 6.x features
Version 6.x of Mesa implements the OpenGL 1.5 API with the following
extensions incorporated as standard features:
-- GL\_ARB\_occlusion\_query
-- GL\_ARB\_vertex\_buffer\_object
-- GL\_EXT\_shadow\_funcs
+- ``GL_ARB_occlusion_query``
+- ``GL_ARB_vertex_buffer_object``
+- ``GL_EXT_shadow_funcs``
Also note that several OpenGL tokens were renamed in OpenGL 1.5 for the
sake of consistency. The old tokens are still available.
-::
+.. code-block:: c
New Token Old Token
------------------------------------------------------------
@@ -213,23 +213,23 @@ Version 5.x features
Version 5.x of Mesa implements the OpenGL 1.4 API with the following
extensions incorporated as standard features:
-- GL\_ARB\_depth\_texture
-- GL\_ARB\_shadow
-- GL\_ARB\_texture\_env\_crossbar
-- GL\_ARB\_texture\_mirror\_repeat
-- GL\_ARB\_window\_pos
-- GL\_EXT\_blend\_color
-- GL\_EXT\_blend\_func\_separate
-- GL\_EXT\_blend\_logic\_op
-- GL\_EXT\_blend\_minmax
-- GL\_EXT\_blend\_subtract
-- GL\_EXT\_fog\_coord
-- GL\_EXT\_multi\_draw\_arrays
-- GL\_EXT\_point\_parameters
-- GL\_EXT\_secondary\_color
-- GL\_EXT\_stencil\_wrap
-- GL\_EXT\_texture\_lod\_bias (plus, a per-texture LOD bias parameter)
-- GL\_SGIS\_generate\_mipmap
+- ``GL_ARB_depth_texture``
+- ``GL_ARB_shadow``
+- ``GL_ARB_texture_env_crossbar``
+- ``GL_ARB_texture_mirror_repeat``
+- ``GL_ARB_window_pos``
+- ``GL_EXT_blend_color``
+- ``GL_EXT_blend_func_separate``
+- ``GL_EXT_blend_logic_op``
+- ``GL_EXT_blend_minmax``
+- ``GL_EXT_blend_subtract``
+- ``GL_EXT_fog_coord``
+- ``GL_EXT_multi_draw_arrays``
+- ``GL_EXT_point_parameters``
+- ``GL_EXT_secondary_color``
+- ``GL_EXT_stencil_wrap``
+- ``GL_EXT_texture_lod_bias`` (plus, a per-texture LOD bias parameter)
+- ``GL_SGIS_generate_mipmap``
Version 4.x features
--------------------
@@ -237,15 +237,15 @@ Version 4.x features
Version 4.x of Mesa implements the OpenGL 1.3 API with the following
extensions incorporated as standard features:
-- GL\_ARB\_multisample
-- GL\_ARB\_multitexture
-- GL\_ARB\_texture\_border\_clamp
-- GL\_ARB\_texture\_compression
-- GL\_ARB\_texture\_cube\_map
-- GL\_ARB\_texture\_env\_add
-- GL\_ARB\_texture\_env\_combine
-- GL\_ARB\_texture\_env\_dot3
-- GL\_ARB\_transpose\_matrix
+- ``GL_ARB_multisample``
+- ``GL_ARB_multitexture``
+- ``GL_ARB_texture_border_clamp``
+- ``GL_ARB_texture_compression``
+- ``GL_ARB_texture_cube_map``
+- ``GL_ARB_texture_env_add``
+- ``GL_ARB_texture_env_combine``
+- ``GL_ARB_texture_env_dot3``
+- ``GL_ARB_transpose_matrix``
Version 3.x features
--------------------
@@ -255,7 +255,7 @@ features:
- BGR, BGRA and packed pixel formats
- New texture border clamp mode
-- glDrawRangeElements()
+- ``glDrawRangeElements()``
- standard 3-D texturing
- advanced MIPMAP control
- separate specular color interpolation
@@ -268,41 +268,41 @@ features.
- Texture mapping:
- - glAreTexturesResident
- - glBindTexture
- - glCopyTexImage1D
- - glCopyTexImage2D
- - glCopyTexSubImage1D
- - glCopyTexSubImage2D
- - glDeleteTextures
- - glGenTextures
- - glIsTexture
- - glPrioritizeTextures
- - glTexSubImage1D
- - glTexSubImage2D
+ - ``glAreTexturesResident``
+ - ``glBindTexture``
+ - ``glCopyTexImage1D``
+ - ``glCopyTexImage2D``
+ - ``glCopyTexSubImage1D``
+ - ``glCopyTexSubImage2D``
+ - ``glDeleteTextures``
+ - ``glGenTextures``
+ - ``glIsTexture``
+ - ``glPrioritizeTextures``
+ - ``glTexSubImage1D``
+ - ``glTexSubImage2D``
- Vertex Arrays:
- - glArrayElement
- - glColorPointer
- - glDrawElements
- - glEdgeFlagPointer
- - glIndexPointer
- - glInterleavedArrays
- - glNormalPointer
- - glTexCoordPointer
- - glVertexPointer
+ - ``glArrayElement``
+ - ``glColorPointer``
+ - ``glDrawElements``
+ - ``glEdgeFlagPointer``
+ - ``glIndexPointer``
+ - ``glInterleavedArrays``
+ - ``glNormalPointer``
+ - ``glTexCoordPointer``
+ - ``glVertexPointer``
- Client state management:
- - glDisableClientState
- - glEnableClientState
- - glPopClientAttrib
- - glPushClientAttrib
+ - ``glDisableClientState``
+ - ``glEnableClientState``
+ - ``glPopClientAttrib``
+ - ``glPushClientAttrib``
- Misc:
- - glGetPointer
- - glIndexub
- - glIndexubv
- - glPolygonOffset
+ - ``glGetPointer``
+ - ``glIndexub``
+ - ``glIndexubv``
+ - ``glPolygonOffset``
diff --git a/docs/license.rst b/docs/license.rst
index 40387f4dc2..bad1603175 100644
--- a/docs/license.rst
+++ b/docs/license.rst
@@ -8,17 +8,17 @@ Mesa is a 3-D graphics library with an API which is very similar to that
of `OpenGL <https://www.opengl.org/>`__.\* To the extent that Mesa
utilizes the OpenGL command syntax or state machine, it is being used
with authorization from `Silicon Graphics,
-Inc. <https://www.sgi.com/>`__\ (SGI). However, the author does not
+Inc. <https://en.wikipedia.org/wiki/Silicon_Graphics>`__\ (SGI). However, the author does not
possess an OpenGL license from SGI, and makes no claim that Mesa is in
any way a compatible replacement for OpenGL or associated with SGI.
Those who want a licensed implementation of OpenGL should contact a
licensed vendor.
-| Please do not refer to the library as *MesaGL* (for legal reasons).
- It's just *Mesa* or *The Mesa 3-D graphics library*.
+ Please do not refer to the library as *MesaGL* (for legal reasons).
+ It's just *Mesa* or *The Mesa 3-D graphics library*.
\* OpenGL is a trademark of `Silicon Graphics
-Incorporated <https://www.sgi.com/>`__.
+Incorporated <https://en.wikipedia.org/wiki/Silicon_Graphics>`__.
License / Copyright Information
===============================
@@ -35,7 +35,7 @@ projects.
The default Mesa license is as follows:
-::
+.. code-block:: text
Copyright (C) 1999-2007 Brian Paul All Rights Reserved.
@@ -68,7 +68,7 @@ respective licenses.
Mesa Component Licenses
=======================
-::
+.. code-block:: text
Component Location License
------------------------------------------------------------------
diff --git a/docs/llvmpipe.rst b/docs/llvmpipe.rst
index e88bf3d6a7..ff5eff67de 100644
--- a/docs/llvmpipe.rst
+++ b/docs/llvmpipe.rst
@@ -32,7 +32,7 @@ Requirements
For Linux, on a recent Debian based distribution do:
- ::
+ .. code-block:: bash
aptitude install llvm-dev
@@ -43,7 +43,7 @@ Requirements
For a RPM-based distribution do:
- ::
+ .. code-block:: bash
yum install llvm-devel
@@ -54,28 +54,18 @@ Requirements
be built with a matching CRT as Mesa, and you'll need to pass
``-DLLVM_USE_CRT_xxx=yyy`` as described below.
- LLVM build-type
+ +---------------+------------------------------------------------------------+
+ |LLVM build-type| Mesa build-type |
+ | +------------------------------+-----------------------------+
+ | |debug,checked |release,profile |
+ +===============+==============================+=============================+
+ |Debug |``-DLLVM_USE_CRT_DEBUG=MTd`` |``-DLLVM_USE_CRT_DEBUG=MT`` |
+ +---------------+------------------------------+-----------------------------+
+ |Release |``-DLLVM_USE_CRT_RELEASE=MTd``|``-DLLVM_USE_CRT_RELEASE=MT``|
+ +---------------+------------------------------+-----------------------------+
- Mesa build-type
-
- debug,checked
-
- release,profile
-
- Debug
-
- ``-DLLVM_USE_CRT_DEBUG=MTd``
-
- ``-DLLVM_USE_CRT_DEBUG=MT``
-
- Release
-
- ``-DLLVM_USE_CRT_RELEASE=MTd``
-
- ``-DLLVM_USE_CRT_RELEASE=MT``
-
- You can build only the x86 target by passing
- -DLLVM\_TARGETS\_TO\_BUILD=X86 to cmake.
+You can build only the x86 target by passing
+``-DLLVM_TARGETS_TO_BUILD=X86`` to cmake.
- scons (optional)
@@ -84,13 +74,13 @@ Building
To build everything on Linux invoke scons as:
-::
+.. code-block:: bash
scons build=debug libgl-xlib
Alternatively, you can build it with autoconf/make with:
-::
+.. code-block:: bash
./configure --enable-glx=gallium-xlib --with-gallium-drivers=swrast --disable-dri --disable-gbm --disable-egl
make
@@ -98,7 +88,7 @@ Alternatively, you can build it with autoconf/make with:
but the rest of these instructions assume that scons is used. For
Windows the procedure is similar except the target:
-::
+.. code-block:: bash
scons platform=windows build=debug libgl-gdi
@@ -108,7 +98,7 @@ Using
Linux
-----
-On Linux, building will create a drop-in alternative for libGL.so into
+On Linux, building will create a drop-in alternative for ``libGL.so`` into
::
@@ -120,10 +110,10 @@ or
lib/gallium/libGL.so
-To use it set the LD\_LIBRARY\_PATH environment variable accordingly.
+To use it set the ``LD_LIBRARY_PATH`` environment variable accordingly.
-For performance evaluation pass build=release to scons, and use the
-corresponding lib directory without the "-debug" suffix.
+For performance evaluation pass ``build=release`` to scons, and use the
+corresponding lib directory without the ``-debug`` suffix.
Windows
-------
@@ -139,12 +129,12 @@ There is however an easy way to replace the OpenGL software renderer
that comes with Microsoft Windows 7 (or later) with llvmpipe (that is,
on systems without any OpenGL drivers):
-- copy build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll
- to C:\\Windows\\SysWOW64\\mesadrv.dll
+- copy ``build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll``
+ to ``C:\\Windows\\SysWOW64\\mesadrv.dll``
- load this registry settings:
- ::
+ .. code-block:: text
REGEDIT4
@@ -163,7 +153,7 @@ Profiling
To profile llvmpipe you should build as
-::
+.. code-block:: bash
scons build=profile <same-as-before>
@@ -176,10 +166,10 @@ Linux perf integration
On Linux, it is possible to have symbol resolution of JIT code with
`Linux perf <https://perf.wiki.kernel.org/>`__:
-::
+.. code-block:: bash
perf record -g /my/application
- perf report
+ perf report
When run inside Linux perf, llvmpipe will create a /tmp/perf-XXXXX.map
file with symbol address table. It also dumps assembly code to
@@ -203,7 +193,7 @@ build/linux-???-debug/gallium/drivers/llvmpipe:
Some of these tests can output results and benchmarks to a tab-separated
file for later analysis, e.g.:
-::
+.. code-block:: bash
build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
@@ -271,7 +261,6 @@ Recommended Reading
resources <http://www.agner.org/optimize/>`__
- `Intel Intrinsics
Guide <https://software.intel.com/en-us/articles/intel-intrinsics-guide>`__
- -
- LLVM
diff --git a/docs/mangling.rst b/docs/mangling.rst
index 1eeffd3c38..4044296936 100644
--- a/docs/mangling.rst
+++ b/docs/mangling.rst
@@ -7,8 +7,8 @@ application at the same time you may find it useful to compile Mesa with
with **mgl** instead of **gl**.
This option is supported only with the autoconf build. To use it add
---enable-mangling to your configure line.
+``--enable-mangling`` to your configure line.
-::
+.. code-block:: bash
./configure --enable-mangling ...
diff --git a/docs/meson.rst b/docs/meson.rst
index e03949ddd9..e529ab4d1e 100644
--- a/docs/meson.rst
+++ b/docs/meson.rst
@@ -20,7 +20,7 @@ default backend on all operating systems. Meson only supports
out-of-tree builds, and must be passed a directory to put built and
generated sources into. We'll call that directory "build" for examples.
-::
+.. code-block:: bash
meson build/
@@ -31,7 +31,7 @@ defaults and your local settings. Meson does not currently support
listing options before configure a build directory, but this feature is
being discussed upstream.
-::
+.. code-block:: bash
meson configure build/
@@ -39,15 +39,15 @@ With additional arguments ``meson configure`` is used to change options
on already configured build directory. All options passed to this
command are in the form ``-D "command"="value"``.
-::
+.. code-block:: bash
meson configure build/ -Dprefix=/tmp/install -Dglx=true
Once you've run the initial ``meson`` command successfully you can use
-your configured backend to build the project. With ninja, the -C option
+your configured backend to build the project. With ninja, the ``-C`` option
can be be used to point at a directory to build.
-::
+.. code-block:: bash
ninja -C build/
@@ -57,7 +57,7 @@ to rebuild for a different configuration, you should run ``ninja clean``
before changing the configuration, or create a new out of tree build
directory for each configuration you want to build `as recommended in
the
-documentation <http://mesonbuild.com/Using-multiple-build-directories.html>`__
+documentation <http://mesonbuild.com/Using-multiple-build-directories.html>`__.
``Environment Variables``
Meson supports the standard CC and CXX environment variables for
@@ -75,7 +75,7 @@ documentation <http://mesonbuild.com/Using-multiple-build-directories.html>`__
recommended when changing CFLAGS or CXXFLAGS. Meson will never
change compiler in a configured build directory.
- ::
+ .. code-block:: bash
CC=clang CXX=clang++ meson build-clang
ninja -C build-clang
@@ -102,9 +102,9 @@ documentation <http://mesonbuild.com/Using-multiple-build-directories.html>`__
One of the oddities of meson is that some options are different when
passed to the ``meson`` than to ``meson configure``. These options are
-passed as --option=foo to ``meson``, but -Doption=foo to
+passed as ``--option=foo`` to ``meson``, but ``-Doption=foo`` to
``meson configure``. Mesa defined options are always passed as
--Doption=foo.
+``-Doption=foo``.
For those coming from autotools be aware of the following:
diff --git a/docs/osmesa.rst b/docs/osmesa.rst
index 3317b5ed4e..2205152142 100644
--- a/docs/osmesa.rst
+++ b/docs/osmesa.rst
@@ -3,12 +3,12 @@ Off-screen Rendering
Mesa's off-screen interface is used for rendering into user-allocated
memory without any sort of window system or operating system
-dependencies. That is, the GL\_FRONT colorbuffer is actually a buffer in
+dependencies. That is, the ``GL_FRONT`` colorbuffer is actually a buffer in
main memory, rather than a window on your display.
The OSMesa API provides three basic functions for making off-screen
-renderings: OSMesaCreateContext(), OSMesaMakeCurrent(), and
-OSMesaDestroyContext(). See the Mesa/include/GL/osmesa.h header for more
+renderings: ``OSMesaCreateContext()``, ``OSMesaMakeCurrent()``, and
+``OSMesaDestroyContext()``. See the ``Mesa/include/GL/osmesa.h`` header for more
information about the API functions.
The OSMesa interface may be used with any of three software renderers:
@@ -24,7 +24,7 @@ Building OSMesa
Configure and build Mesa with something like:
-::
+.. code-block:: bash
configure --enable-osmesa --disable-driglx-direct --disable-dri --with-gallium-drivers=swrast
make
@@ -39,7 +39,7 @@ When the build is complete you should find:
lib/libOSMesa.so (swrast-based OSMesa)
lib/gallium/libOSMsea.so (gallium-based OSMesa)
-Set your LD\_LIBRARY\_PATH to point to one directory or the other to
+Set your ``LD_LIBRARY_PATH`` to point to one directory or the other to
select the library you want to use.
-When you link your application, link with -lOSMesa
+When you link your application, link with ``-lOSMesa``.
diff --git a/docs/perf.rst b/docs/perf.rst
index 5907a7fe8b..bf14549db3 100644
--- a/docs/perf.rst
+++ b/docs/perf.rst
@@ -3,42 +3,73 @@ Performance Tips
Performance tips for software rendering:
-#. Turn off smooth shading when you don't need it (glShadeModel)
+#. Turn off smooth shading when you don't need it (``glShadeModel``)
#. Turn off depth buffering when you don't need it.
#. Turn off dithering when not needed.
#. Use double buffering as it's often faster than single buffering
#. Compile in the X Shared Memory extension option if it's supported on
- your system by adding -DSHM to CFLAGS and -lXext to XLIBS for your
+ your system by adding ``-DSHM`` to CFLAGS and ``-lXext`` to XLIBS for your
system in the Make-config file.
#. Recompile Mesa with more optimization if possible.
#. Try to maximize the amount of drawing done between glBegin/glEnd
pairs.
-#. Use the MESA\_BACK\_BUFFER variable to find best performance in
+#. Use the ``MESA_BACK_BUFFER`` variable to find best performance in
double buffered mode. (X users only)
-#. Optimized polygon rasterizers are employed when: rendering into back
- buffer which is an XImage RGB mode, not grayscale, not monochrome
- depth buffering is GL\_LESS, or disabled flat or smooth shading
- dithered or non-dithered no other rasterization operations enabled
- (blending, stencil, etc)
-#. Optimized line drawing is employed when: rendering into back buffer
- which is an XImage RGB mode, not grayscale, not monochrome depth
- buffering is GL\_LESS or disabled flat shading dithered or
- non-dithered no other rasterization operations enabled (blending,
- stencil, etc)
-#. Textured polygons are fastest when: using a 3-component (RGB), 2-D
- texture minification and magnification filters are GL\_NEAREST
- texture coordinate wrap modes for S and T are GL\_REPEAT GL\_DECAL
- environment mode glHint( GL\_PERSPECTIVE\_CORRECTION\_HINT,
- GL\_FASTEST ) depth buffering is GL\_LESS or disabled
-#. Lighting is fastest when: Two-sided lighting is disabled
- GL\_LIGHT\_MODEL\_LOCAL\_VIEWER is false GL\_COLOR\_MATERIAL is
- disabled No spot lights are used (all GL\_SPOT\_CUTOFFs are 180.0) No
- local lights are used (all position W's are 0.0) All material and
- light coefficients are >= zero
+#. Optimized polygon rasterizers are employed when
+
+ - rendering into back buffer which is an XImage RGB mode,
+ not grayscale, not monochrome
+
+ - depth buffering is ``GL_LESS``, or disabled
+
+ - flat or smooth shading dithered or non-dithered
+
+ - no other rasterization operations enabled
+ (blending, stencil, etc)
+
+#. Optimized line drawing is employed when
+
+ - rendering into back buffer which is an XImage RGB mode,
+ not grayscale, not monochrome depth
+
+ - buffering is ``GL_LESS`` or disabled
+
+ - flat shading dithered or non-dithered
+
+ - no other rasterization operations enabled (blending,
+ stencil, etc)
+
+#. Textured polygons are fastest when
+
+ - using a 3-component (RGB)
+
+ - 2-D texture minification and magnification filters are ``GL_NEAREST``
+
+ - texture coordinate wrap modes for S and T are ``GL_REPEAT`` ``GL_DECAL``
+
+ - environment mode ``glHint( GL_PERSPECTIVE_CORRECTION_HINT,
+ GL_FASTEST )``
+
+ - depth buffering is ``GL_LESS`` or disabled
+
+#. Lighting is fastest when:
+
+ - Two-sided lighting is disabled
+
+ - ``GL_LIGHT_MODEL_LOCAL_VIEWER`` is false
+
+ - ``GL_COLOR_MATERIAL`` is disabled
+
+ - No spot lights are used (all ``GL_SPOT_CUTOFFs`` are 180.0)
+
+ - No local lights are used (all position W's are 0.0)
+
+ - All material and light coefficients are >= zero
+
#. XFree86 users: if you want to use 24-bit color try starting your X
server in 32-bit per pixel mode for better performance. That is,
- start your X server with startx -- -bpp 32 instead of startx -- -bpp
- 24
-#. Try disabling dithering with the MESA\_NO\_DITHER environment
+ start your X server with ``startx -- -bpp 32`` instead of ``startx -- -bpp
+ 24``
+#. Try disabling dithering with the ``MESA_NO_DITHER`` environment
variable. If this env var is defined Mesa will disable dithering and
- the command glEnable(GL\_DITHER) will be ignored.
+ the command ``glEnable(GL_DITHER)`` will be ignored.
diff --git a/docs/postprocess.rst b/docs/postprocess.rst
index 3135323eec..5a1a43b232 100644
--- a/docs/postprocess.rst
+++ b/docs/postprocess.rst
@@ -14,22 +14,21 @@ Multiple filters can be used together.
PP environment variables
------------------------
-- PP\_DEBUG - If defined debug information will be printed to stderr.
+``PP_DEBUG``
+ If defined debug information will be printed to stderr.
Current filters
---------------
-- pp\_nored, pp\_nogreen, pp\_noblue - set to 1 to remove the
+- ``pp_nored``, ``pp_nogreen``, ``pp_noblue`` - set to 1 to remove the
corresponding color channel. These are basic filters for easy testing
of the PP queue.
-- pp\_jimenezmlaa, pp\_jimenezmlaa\_color - `Jimenez's
+- ``pp_jimenezmlaa``, ``pp_jimenezmlaa_color`` - `Jimenez's
MLAA <https://www.iryokufx.com/mlaa/>`__ is a morphological
antialiasing filter. The two versions use depth and color data,
respectively. Which works better depends on the app - depth will not
blur text, but it will miss transparent textures for example. Set to
a number from 2 to 32, roughly corresponding to quality. Numbers
higher than 8 see minimizing gains.
-- pp\_celshade - set to 1 to enable cell shading (a more complex color
+- ``pp_celshade`` - set to 1 to enable cell shading (a more complex color
filter).
-
-|
diff --git a/docs/precompiled.rst b/docs/precompiled.rst
index 5197fa4902..5b4ede1539 100644
--- a/docs/precompiled.rst
+++ b/docs/precompiled.rst
@@ -3,9 +3,9 @@ Precompiled Libraries
In general, precompiled Mesa libraries are not available.
-| Some Linux distributions closely follow the latest Mesa releases. On
- others one has to use unofficial channels.
-| There are some general directions:
+Some Linux distributions closely follow the latest Mesa releases. On
+others one has to use unofficial channels.
+There are some general directions:
Debian/Ubuntu based distros - PPA: xorg-edgers, oibaf and padoka
diff --git a/docs/release-calendar.rst b/docs/release-calendar.rst
index 1112f6809b..44d4314b60 100644
--- a/docs/release-calendar.rst
+++ b/docs/release-calendar.rst
@@ -3,112 +3,58 @@ Overview
Mesa provides feature/development and stable releases.
-| The table below lists the date and release manager that is expected to
- do the specific release.
-| Take a look `here <submittingpatches.html#criteria>`__ if you'd like
- to nominate a patch in the next stable release.
+The table below lists the date and release manager that is expected to
+do the specific release.
+Take a look `here <submittingpatches.html#criteria>`__ if you'd like
+to nominate a patch in the next stable release.
Calendar
========
-
-Branch
-
-Expected date
-
-Release
-
-Release manager
-
-Notes
-
-18.0
-
-2018-06-01
-
-18.0.5
-
-Juan A. Suarez Romero
-
-Last planned 18.0.x release
-
-18.1
-
-2018-04-20
-
-18.1.0rc1
-
-Dylan Baker
-
-2018-04-27
-
-18.1.0rc2
-
-Dylan Baker
-
-2018-05-04
-
-18.1.0rc3
-
-Dylan Baker
-
-2018-05-11
-
-18.1.0rc4
-
-Dylan Baker
-
-Last planned RC/Final release
-
-TBD
-
-18.1.1
-
-Emil Velikov
-
-TBD
-
-18.1.2
-
-Emil Velikov
-
-TBD
-
-18.1.3
-
-Emil Velikov
-
-TBD
-
-18.1.4
-
-Emil Velikov
-
-Last planned RC/Final release
-
-18.2
-
-2018-07-20
-
-18.2.0rc1
-
-Andres Gomez
-
-2018-07-27
-
-18.2.0rc2
-
-Andres Gomez
-
-2018-08-03
-
-18.2.0rc3
-
-Andres Gomez
-
-2018-08-10
-
-18.2.0rc4
-
-Andres Gomez
-
-Last planned RC/Final release
+====== ============= ========= ===================== =============================
+Branch Expected date Release Release manager Notes
+====== ============= ========= ===================== =============================
+18.0 2018-06-01 18.0.5 Juan A. Suarez Romero Last planned 18.0.x release
+18.1 2018-04-20 18.1.0rc1 Dylan Baker \
+\ 2018-04-27 18.1.0rc2 Dylan Baker \
+\ 2018-05-04 18.1.0rc3 Dylan Baker \
+\ 2018-05-11 18.1.0rc4 Dylan Baker Last planned RC/Final release
+\ TBD 18.1.1 Emil Velikov \
+\ TBD 18.1.2 Emil Velikov \
+\ TBD 18.1.3 Emil Velikov \
+\ TBD 18.1.4 Emil Velikov Last planned RC/Final release
+18.2 2018-07-20 18.2.0rc1 Andres Gomez \
+\ 2018-07-27 18.2.0rc2 Andres Gomez \
+\ 2018-08-03 18.2.0rc3 Andres Gomez \
+\ 2018-08-10 18.2.0rc4 Andres Gomez Last planned RC/Final release
+====== ============= ========= ===================== =============================
+
+.. Other table style, in case we end up liking it better.
+ +------+-------------+---------+---------------------+-----------------------------+
+ |Branch|Expected date|Release |Release manager |Notes |
+ +======+=============+=========+=====================+=============================+
+ |18.0 |2018-06-01 |18.0.5 |Juan A. Suarez Romero|Last planned 18.0.x release |
+ +------+-------------+---------+---------------------+-----------------------------+
+ |18.1 |2018-04-20 |18.1.0rc1|Dylan Baker | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |2018-04-27 |18.1.0rc2|Dylan Baker | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |2018-05-04 |18.1.0rc3|Dylan Baker | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |2018-05-11 |18.1.0rc4|Dylan Baker |Last planned RC/Final release|
+ | +-------------+---------+---------------------+-----------------------------+
+ | |TBD |18.1.1 |Emil Velikov | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |TBD |18.1.2 |Emil Velikov | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |TBD |18.1.3 |Emil Velikov | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |TBD |18.1.4 |Emil Velikov |Last planned RC/Final release|
+ +------+-------------+---------+---------------------+-----------------------------+
+ |18.2 |2018-07-20 |18.2.0rc1|Andres Gomez | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |2018-07-27 |18.2.0rc2|Andres Gomez | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |2018-08-03 |18.2.0rc3|Andres Gomez | |
+ | +-------------+---------+---------------------+-----------------------------+
+ | |2018-08-10 |18.2.0rc4|Andres Gomez |Last planned RC/Final release|
+ +------+-------------+---------+---------------------+-----------------------------+
diff --git a/docs/releasing.rst b/docs/releasing.rst
index aa3dec0e8f..9ad72617c0 100644
--- a/docs/releasing.rst
+++ b/docs/releasing.rst
@@ -14,27 +14,27 @@ Releasing process
Overview
========
-| This document uses the convention X.Y.Z for the release number with
- X.Y being the stable branch name.
-| Mesa provides feature and bugfix releases. Former use zero as patch
- version (Z), while the latter have a non-zero one.
+This document uses the convention X.Y.Z for the release number with
+X.Y being the stable branch name.
+Mesa provides feature and bugfix releases. Former use zero as patch
+version (Z), while the latter have a non-zero one.
For example:
-::
+.. code-block:: text
Mesa 10.1.0 - 10.1 branch, feature
- Mesa 10.1.4 - 10.1 branch, bugfix
- Mesa 12.0.0 - 12.0 branch, feature
- Mesa 12.0.2 - 12.0 branch, bugfix
+ Mesa 10.1.4 - 10.1 branch, bugfix
+ Mesa 12.0.0 - 12.0 branch, feature
+ Mesa 12.0.2 - 12.0 branch, bugfix
Release schedule
================
-| Releases should happen on Fridays. Delays can occur although those
- should be keep to a minimum.
-| See our `calendar <release-calendar.html>`__ for the date and other
- details for individual releases.
+Releases should happen on Fridays. Delays can occur although those
+should be keep to a minimum.
+See our `calendar <release-calendar.html>`__ for the date and other
+details for individual releases.
Feature releases
----------------
@@ -53,10 +53,10 @@ Stable releases
- A `pre-release <#prerelease>`__ announcement should be available
approximately 48 hours before the actual release.
-| Note: There is one or two releases overlap when changing branches. For
- example:
-| The final release from the 12.0 series Mesa 12.0.5 will be out around
- the same time (or shortly after) 13.0.1 is out.
+ **Note**: There is one or two releases overlap when changing branches. For
+ example:
+ The final release from the 12.0 series Mesa 12.0.5 will be out around
+ the same time (or shortly after) 13.0.1 is out.
Cherry-picking and testing
==========================
@@ -95,24 +95,27 @@ Achieved by combination of local ad-hoc scripts, mingw-w64 cross
compilation and AppVeyor plus Travis-CI, the latter as part of their
Github integration.
-For Windows related changes, the main contact point is Brian Paul. Jose
-Fonseca can also help as a fallback contact.
+For Windows related changes,
+ the main contact point is Brian Paul. Jose
+ Fonseca can also help as a fallback contact.
-For Android related changes, the main contact is Tapani Pälli. Mauro
-Rossi is collaborating with android-x86 and may provide feedback about
-the build status in that project.
+For Android related changes,
+ the main contact is Tapani Pälli. Mauro
+ Rossi is collaborating with android-x86 and may provide feedback about
+ the build status in that project.
-For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
-good contact point.
+For MacOSX related changes,
+ Jeremy Huddleston Sequoia is currently a
+ good contact point.
-| **Note:** If a patch in the current queue needs any additional
- fix(es), then they should be squashed together.
-| The commit messages and the ``cherry picked from`` tags must be
- preserved.
+**Note:** If a patch in the current queue needs any additional
+fix(es), then they should be squashed together.
+The commit messages and the ``cherry picked from`` tags must be
+preserved.
This should be noted in the `pre-announce <#prerelease>`__ email.
-::
+.. code-block:: text
git show b10859ec41d09c57663a258f43fe57c12332698e
@@ -162,26 +165,26 @@ Making a branchpoint
A branchpoint is made such that new development can continue in parallel
to stabilisation and bugfixing.
-| Note: Before doing a branch ensure that basic build and ``make check``
- testing is done and there are little to-no issues.
-| Ideally all of those should be tackled already.
+ **Note**: Before doing a branch ensure that basic build and ``make check``
+ testing is done and there are little to-no issues.
+ Ideally all of those should be tackled already.
Check if the version number is going to remain as, alternatively
-`` git mv docs/relnotes/{current,new}.html `` as appropriate.
+``git mv docs/relnotes/{current,new}.rst`` as appropriate.
To setup the branchpoint:
-::
+.. code-block:: bash
git checkout master # make sure we're in master first
- git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
- git checkout -b X.Y
- git checkout master
- $EDITOR VERSION # bump the version number
- git commit -as
- cp docs/relnotes/{X.Y,X.Y+1}.html # copy/create relnotes template
- git commit -as
- git push origin X.Y-branchpoint X.Y
+ git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
+ git checkout -b X.Y
+ git checkout master
+ $EDITOR VERSION # bump the version number
+ git commit -as
+ cp docs/relnotes/{X.Y,X.Y+1}.html # copy/create relnotes template
+ git commit -as
+ git push origin X.Y-branchpoint X.Y
Now go to
`Bugzilla <https://bugs.freedesktop.org/editversions.cgi?action=add&product=Mesa>`__
@@ -197,12 +200,12 @@ Proceed to `release <#release>`__ -rc1.
Pre-release announcement
========================
-| It comes shortly after outstanding patches in the respective branch
- are pushed. Developers can check, in brief, what's the status of their
- patches. They, alongside very early testers, are strongly encouraged
- to test the branch and report any regressions.
-| It is followed by a brief period (normally 24 or 48 hours) before the
- actual release is made.
+It comes shortly after outstanding patches in the respective branch
+are pushed. Developers can check, in brief, what's the status of their
+patches. They, alongside very early testers, are strongly encouraged
+to test the branch and report any regressions.
+It is followed by a brief period (normally 24 or 48 hours) before the
+actual release is made.
Be aware to add a note to warn about a final release in a series, if
that is the case.
@@ -210,26 +213,23 @@ that is the case.
Terminology used
----------------
-- Nominated
+Nominated
+ Patch that is nominated but yet to to merged in the patch queue/branch.
-Patch that is nominated but yet to to merged in the patch queue/branch.
+Queued
+ Patch is in the queue/branch and will feature in the next release.
+ Barring reported regressions or objections from developers.
-- Queued
-
-Patch is in the queue/branch and will feature in the next release.
-Barring reported regressions or objections from developers.
-
-- Rejected
-
-| Patch does not fit the `criteria <submittingpatches.html#criteria>`__
- and is followed by a brief information.
-| The release maintainer is human so if you believe you've spotted a
- mistake do let them know.
+Rejected
+ Patch does not fit the `criteria <submittingpatches.html#criteria>`__
+ and is followed by a brief information.
+ The release maintainer is human so if you believe you've spotted a
+ mistake do let them know.
Format/template
---------------
-::
+.. code-block:: text
Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
To: mesa-announce at ...
@@ -360,9 +360,9 @@ So we do a quick 'touch test'
Here is one solution that I've been using.
-::
+.. code-block:: bash
- # Set MAKEFLAGS if you haven't already
+ # Set MAKEFLAGS if you haven't already
git clean -fXd; git clean -nxd
read # quick cross check any outstanding files
export __version=`cat VERSION`
@@ -459,10 +459,10 @@ notes should be empty (TBD) at this point.
Two scripts are available to help generate portions of the release
notes:
-::
+.. code-block:: bash
./bin/bugzilla_mesa.sh
- ./bin/shortlog_mesa.sh
+ ./bin/shortlog_mesa.sh
The first script identifies commits that reference bugzilla bugs and
obtains the descriptions of those bugs from bugzilla. The second script
@@ -471,7 +471,7 @@ printed to stdout to be included in the release notes.
Commit these changes and push the branch.
-::
+.. code-block:: bash
git push origin HEAD
@@ -480,11 +480,11 @@ Use the release.sh script from xorg `util-modular <https://cgit.freedesktop.org/
Start the release process.
-::
+.. code-block:: bash
# For the dist/distcheck, you may want to specify which LLVM to use:
- # export LLVM_CONFIG=/usr/lib/llvm-3.9/bin/llvm-config
- ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
+ # export LLVM_CONFIG=/usr/lib/llvm-3.9/bin/llvm-config
+ ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
Pay close attention to the prompts as you might be required to enter
your GPG and SSH passphrase(s) to sign and upload the files,
@@ -501,20 +501,20 @@ Back on mesa master, add the new release notes into the tree
Something like the following steps will do the trick:
-::
+.. code-block:: bash
git cherry-pick -x X.Y~1
- git cherry-pick -x X.Y
+ git cherry-pick -x X.Y
Also, edit docs/relnotes.html to add a link to the new release notes,
edit docs/index.html to add a news entry and a note in case of the last
release in a series, and remove the version from
docs/release-calendar.html. Then commit and push:
-::
+.. code-block:: bash
git commit -as -m "docs: update calendar, add news item and link release notes for X.Y.Z"
- git push origin master X.Y
+ git push origin master X.Y
Announce the release
====================
@@ -534,10 +534,10 @@ the final ``git push``
Update Bugzilla
===============
-| Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
- document.
-| If there's outstanding action, close the bug referencing the commit ID
- which addresses the bug and mention the Mesa version that has the fix.
+Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
+document.
+If there's outstanding action, close the bug referencing the commit ID
+which addresses the bug and mention the Mesa version that has the fix.
-Note: the above is not applicable to all the reports, so use common
-sense.
+ **Note**: the above is not applicable to all the reports, so use common
+ sense.
diff --git a/docs/repository.rst b/docs/repository.rst
index 8b0cea5d34..bdbaf9a37f 100644
--- a/docs/repository.rst
+++ b/docs/repository.rst
@@ -24,24 +24,24 @@ To get the Mesa sources anonymously (read-only):
#. Install the git software on your computer if needed.
#. Get an initial, local copy of the repository with:
- ::
+ .. code-block:: bash
git clone git://anongit.freedesktop.org/git/mesa/mesa
-
+
#. Later, you can update your tree from the master repository with:
- ::
+ .. code-block:: bash
git pull origin
-
+
#. If you also want the Mesa demos/tests repository:
- ::
+ .. code-block:: bash
git clone git://anongit.freedesktop.org/git/mesa/demos
-
+
Developer git Access
--------------------
@@ -78,26 +78,25 @@ Once your account is established:
#. Get an initial, local copy of the repository with:
- ::
+ .. code-block:: bash
git clone git+ssh://username@git.freedesktop.org/git/mesa/mesa
-
- | Replace *username* with your actual login name.
+ Replace *username* with your actual login name.
#. Later, you can update your tree from the master repository with:
- ::
+ .. code-block:: bash
git pull origin
-
+
#. If you also want the Mesa demos/tests repository:
- ::
+ .. code-block:: bash
git clone git+ssh://username@git.freedesktop.org/git/mesa/demos
-
+
Windows Users
-------------
@@ -107,7 +106,7 @@ Windows <https://git.wiki.kernel.org/index.php/WindowsInstall>`__ you'll
want to enable automatic CR/LF conversion in your local copy of the
repository:
-::
+.. code-block:: bash
git config --global core.autocrlf true
@@ -116,8 +115,6 @@ to LF on commit.
Unix users don't need to set this option.
-|
-
Development Branches
--------------------
@@ -135,16 +132,16 @@ Developer Git Tips
#. Setting up to edit the master branch
- If you try to do a pull by just saying\ `` git pull `` and git
+ If you try to do a pull by just saying\ ``git pull`` and git
complains that you have not specified a branch, try:
- ::
+ .. code-block:: bash
git config branch.master.remote origin
git config branch.master.merge master
- Otherwise, you have to say\ `` git pull origin master `` each time
- you do a pull.
+ Otherwise, you have to say ``git pull origin master`` each time
+ you do a pull.
#. Small changes to master
@@ -157,7 +154,7 @@ Developer Git Tips
If it has been awhile since you've done the initial clone, try
- ::
+ .. code-block:: bash
git pull
@@ -165,7 +162,7 @@ Developer Git Tips
Make your changes and use
- ::
+ .. code-block:: bash
git add <files to commit>
git commit
@@ -180,18 +177,18 @@ Developer Git Tips
To avoid this,
- ::
+ .. code-block:: bash
git pull --rebase
git push
- | If you are familiar with CVS or similar system, this is similar to
- doing a `` cvs update `` in order to update your source tree to the
- current repository state, instead of the time you did the last
- update. (CVS doesn't work like git in this respect, but this is
- easiest way to explain it.)
- | In any case, your repository now looks like you made your changes
- after all the other changes.
+ If you are familiar with CVS or similar system, this is similar to
+ doing a ``cvs update`` in order to update your source tree to the
+ current repository state, instead of the time you did the last
+ update. (CVS doesn't work like git in this respect, but this is
+ easiest way to explain it.)
+ In any case, your repository now looks like you made your changes
+ after all the other changes.
If the rebase resulted in conflicts or changes that could affect the
proper operation of your changes, you'll need to investigate those
@@ -199,7 +196,7 @@ Developer Git Tips
If you want the rebase action to be the default action, then
- ::
+ .. code-block:: bash
git config branch.master.rebase true
git config --global branch.autosetuprebase=always
diff --git a/docs/shading.rst b/docs/shading.rst
index 27cbd7b438..0cf54fa331 100644
--- a/docs/shading.rst
+++ b/docs/shading.rst
@@ -18,25 +18,44 @@ Contents
Environment Variables
---------------------
-The **MESA\_GLSL** environment variable can be set to a comma-separated
+The ``MESA_GLSL`` environment variable can be set to a comma-separated
list of keywords to control some aspects of the GLSL compiler and shader
execution. These are generally used for debugging.
-- **dump** - print GLSL shader code to stdout at link time
-- **log** - log all GLSL shaders to files. The filenames will be
- "shader\_X.vert" or "shader\_X.frag" where X the shader ID.
-- **cache\_info** - print debug information about shader cache
-- **cache\_fb** - force cached shaders to be ignored and do a full
+``dump``
+ print GLSL shader code to stdout at link time
+
+``log``
+ log all GLSL shaders to files. The filenames will be
+ ``shader_X.vert`` or ``shader_X.frag`` where X is the shader ID.
+
+``cache_info``
+ print debug information about shader cache
+
+``cache_fb``
+ force cached shaders to be ignored and do a full
recompile via the fallback path
-- **uniform** - print message to stdout when glUniform is called
-- **nopvert** - force vertex shaders to be a simple shader that just
- transforms the vertex position with ftransform() and passes through
+
+``uniform``
+ print message to stdout when ``glUniform`` is called
+
+``nopvert``
+ force vertex shaders to be a simple shader that just
+ transforms the vertex position with ``ftransform()`` and passes through
the color and texcoord[0] attributes.
-- **nopfrag** - force fragment shader to be a simple shader that passes
+
+``nopfrag``
+ force fragment shader to be a simple shader that passes
through the color attribute.
-- **useprog** - log glUseProgram calls to stderr
-Example: export MESA\_GLSL=dump,nopt
+``useprog``
+ log ``glUseProgram`` calls to stderr
+
+Example:
+
+.. code-block:: bash
+
+ export MESA_GLSL=dump,nopt
Experimenting with Shader Replacements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -45,8 +64,11 @@ Shaders can be dumped and replaced on runtime for debugging purposes.
This feature is not currently supported by SCons build. This is
controlled via following environment variables:
-- **MESA\_SHADER\_DUMP\_PATH** - path where shader sources are dumped
-- **MESA\_SHADER\_READ\_PATH** - path where replacement shaders are
+``MESA_SHADER_DUMP_PATH``
+ path where shader sources are dumped
+
+``MESA_SHADER_READ_PATH``
+ path where replacement shaders are
read
Note, path set must exist before running for dumping or replacing to
@@ -58,7 +80,7 @@ dumped shaders.
Capturing Shaders
~~~~~~~~~~~~~~~~~
-Setting **MESA\_SHADER\_CAPTURE\_PATH** to a directory will cause the
+Setting ``MESA_SHADER_CAPTURE_PATH`` to a directory will cause the
compiler to write ``.shader_test`` files for use with
`shader-db <https://cgit.freedesktop.org/mesa/shader-db>`__, a tool
which compiler developers can use to gather statistics about shaders
@@ -90,7 +112,7 @@ supported in Mesa:
- Linking of multiple shaders does not always work. Currently, linking
is implemented through shader concatenation and re-compiling. This
doesn't always work because of some #pragma and preprocessor issues.
-- The gl\_Color and gl\_SecondaryColor varying vars are interpolated
+- The ``gl_Color`` and ``gl_SecondaryColor`` varying vars are interpolated
without perspective correction
All other major features of the shading language should function.
@@ -99,7 +121,7 @@ Implementation Notes
--------------------
- Shading language programs are compiled into low-level programs very
- similar to those of GL\_ARB\_vertex/fragment\_program.
+ similar to those of ``GL_ARB_vertex/fragment_program``.
- All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
float[4] registers.
- Float constants and variables are packed so that up to four floats
@@ -109,7 +131,7 @@ Implementation Notes
- The quality of generated code is pretty good, register usage is fair.
- Shader error detection and reporting of errors (InfoLog) is not very
good yet.
-- The ftransform() function doesn't necessarily match the results of
+- The ``ftransform()`` function doesn't necessarily match the results of
fixed-function transformation.
These issues will be addressed/resolved in the future.
@@ -120,13 +142,13 @@ Programming Hints
- Use the built-in library functions whenever possible. For example,
instead of writing this:
- ::
+ .. code-block:: glsl
float x = 1.0 / sqrt(y);
Write this:
- ::
+ .. code-block:: glsl
float x = inversesqrt(y);
@@ -143,25 +165,38 @@ This tool is useful for:
- Debugging the GLSL compiler itself
After building Mesa, the compiler can be found at
-src/compiler/glsl/glsl\_compiler
+``src/compiler/glsl/glsl_compiler``
Here's an example of using the compiler to compile a vertex shader and
-emit GL\_ARB\_vertex\_program-style instructions:
+emit ``GL_ARB_vertex_program``-style instructions:
-::
+.. code-block:: bash
src/compiler/glsl/glsl_compiler --version XXX --dump-ast myshader.vert
Options include
-- **--dump-ast** - dump GPU code
-- **--dump-hir** - dump high-level IR code
-- **--dump-lir** - dump low-level IR code
-- **--dump-builder** - dump GLSL IR code
-- **--link** - link shaders
-- **--just-log** - display only shader / linker info if exist, without
+``--dump-ast``
+ dump GPU code
+
+``--dump-hir``
+ dump high-level IR code
+
+``--dump-lir``
+ dump low-level IR code
+
+``--dump-builder``
+ dump GLSL IR code
+
+``--link``
+ link shaders
+
+``--just-log``
+ display only shader / linker info if exist, without
any header or separator
-- **--version** - [Mandatory] define the GLSL version to use
+
+``--version``
+ [Mandatory] define the GLSL version to use
Compiler Implementation
-----------------------
@@ -172,8 +207,8 @@ The source code for Mesa's shading language compiler is in the
XXX provide some info about the compiler....
The final vertex and fragment programs may be interpreted in software
-(see prog\_execute.c) or translated into a specific hardware
-architecture (see drivers/dri/i915/i915\_fragprog.c for example).
+(see ``prog_execute.c``) or translated into a specific hardware
+architecture (see ``drivers/dri/i915/i915_fragprog.c`` for example).
Compiler Validation
-------------------
diff --git a/docs/sourcetree.rst b/docs/sourcetree.rst
index 817e54844b..691e1d5894 100644
--- a/docs/sourcetree.rst
+++ b/docs/sourcetree.rst
@@ -18,11 +18,11 @@ each directory.
- **drivers** - EGL drivers
- **main** - main EGL library implementation. This is where all
- the EGL API functions are implemented, like eglCreateContext().
+ the EGL API functions are implemented, like ``eglCreateContext()``.
- **mapi** - Mesa APIs
- **glapi** - OpenGL API dispatch layer. This is where all the GL
- entrypoints like glClear, glBegin, etc. are generated, as well as
+ entrypoints like ``glClear``, ``glBegin``, etc. are generated, as well as
the GL dispatch table. All GL function calls jump through the
dispatch table to functions found in main/.
- **mesa** - Main Mesa sources
@@ -57,14 +57,14 @@ each directory.
lines, triangles, bitmaps, images, etc. in software. (not used
with Gallium)
- **swrast\_setup** - Software primitive setup. Does things like
- polygon culling, glPolygonMode, polygon offset, etc. (not used
+ polygon culling, ``glPolygonMode``, polygon offset, etc. (not used
with Gallium)
- **tnl** - Software vertex Transformation 'n Lighting. (not used
with Gallium)
- **tnl\_dd** - TNL code for device drivers. (not used with
Gallium)
- **vbo** - Vertex Buffer Object code. All drawing with
- glBegin/glEnd, glDrawArrays, display lists, etc. goes through
+ ``glBegin/glEnd``, ``glDrawArrays``, display lists, etc. goes through
this module. The results is a well-defined set of vertex arrays
which are passed to the device driver (or tnl module) for
rendering.
@@ -143,6 +143,6 @@ each directory.
- **glx** - The GLX library code for building libGL using DRI
drivers.
-- **lib** - hardlinks to most binaries as produced by **make**. These
+- **lib** - hardlinks to most binaries as produced by ``make``. These
(shortcuts) are used for development purposes in conjunction with
- LD\_LIBRARY\_PATH and/or LIBGL\_DRIVERS\_PATH.
+ ``LD_LIBRARY_PATH`` and/or ``LIBGL_DRIVERS_PATH``.
diff --git a/docs/submittingpatches.rst b/docs/submittingpatches.rst
index 186ee7e494..4a5a8a4ef9 100644
--- a/docs/submittingpatches.rst
+++ b/docs/submittingpatches.rst
@@ -37,7 +37,7 @@ Patch formatting
- The first line should be a short, concise summary of the change
prefixed with a module name. Examples:
- ::
+ .. code-block:: text
mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG
@@ -48,10 +48,10 @@ Patch formatting
- Subsequent patch comments should describe the change in more detail,
if needed. For example:
- ::
+ .. code-block:: text
i965: Remove end-of-thread SEND alignment code.
-
+
This was present in Eric's initial implementation of the compaction code
for Sandybridge (commit 077d01b6). There is no documentation saying this
is necessary, and removing it causes no regressions in piglit on any
@@ -61,28 +61,28 @@ Patch formatting
- If a patch addresses a bugzilla issue, that should be noted in the
patch comment. For example:
- ::
+ .. code-block:: text
Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689
- If a patch addresses a issue introduced with earlier commit, that
should be noted in the patch comment. For example:
- ::
+ .. code-block:: text
Fixes: d7b3707c612 "util/disk_cache: use stat() to check if entry is a directory"
- If there have been several revisions to a patch during the review
process, they should be noted such as in this example:
- ::
+ .. code-block:: text
st/mesa: add ARB_texture_stencil8 support (v4)
-
+
if we support stencil texturing, enable texture_stencil8
there is no requirement to support native S8 for this,
the texture can be converted to x24s8 fine.
-
+
v2: fold fixes from Marek in:
a) put S8 last in the list
b) fix renderable to always test for d/s renderable
@@ -93,14 +93,14 @@ Patch formatting
- If someone tested your patch, document it with a line like this:
- ::
+ .. code-block:: text
Tested-by: Joe Hacker <jhacker at foo.com>
- If the patch was reviewed (usually the case) or acked by someone,
that should be documented with:
- ::
+ .. code-block:: text
Reviewed-by: Joe Hacker <jhacker at foo.com>
Acked-by: Joe Hacker <jhacker at foo.com>
@@ -108,12 +108,12 @@ Patch formatting
- If sending later revision of a patch, add all the tags - ack, r-b,
Cc: mesa-stable and/or other. This provides reviewers with quick
feedback if the patch has already been reviewed.
-- | In order for your patch to reach the prospective reviewer
- easier/faster, use the script scripts/get\_reviewer.pl to get a
- list of individuals and include them in the CC list.
- | Please use common sense and do **not** blindly add everyone.
+- In order for your patch to reach the prospective reviewer
+ easier/faster, use the script ``scripts/get_reviewer.pl`` to get a
+ list of individuals and include them in the CC list.
+ Please use common sense and do **not** blindly add everyone.
- ::
+ .. code-block:: bash
$ scripts/get_reviewer.pl --help # to get the help screen
$ scripts/get_reviewer.pl -f src/egl/drivers/dri2/platform_android.c
@@ -128,7 +128,7 @@ It should go without saying that patches must be tested. In general, do
whatever testing is prudent.
You should always run the Mesa test suite before submitting patches. The
-test suite can be run using the 'make check' command. All tests must
+test suite can be run using the ``make check`` command. All tests must
pass before patches will be accepted, this may mean you have to update
the tests themselves.
@@ -138,11 +138,11 @@ Whenever possible and applicable, test the patch with
check for regressions.
As mentioned at the begining, patches should be bisectable. A good way
-to test this is to make use of the \`git rebase\` command, to run your
+to test this is to make use of the ``git rebase`` command, to run your
tests on each commit. Assuming your branch is based off
``origin/master``, you can run:
-::
+.. code-block:: bash
$ git rebase --interactive --exec "make check" origin/master
@@ -158,23 +158,23 @@ send-email <https://git-scm.com/docs/git-send-email>`__ rather than
attaching patches to emails. Sending patches as attachments prevents
people from being able to provide in-line review comments.
-When submitting follow-up patches you can use --in-reply-to to make v2,
+When submitting follow-up patches you can use ``--in-reply-to`` to make v2,
v3, etc patches show up as replies to the originals. This usually works
well when you're sending out updates to individual patches (as opposed
-to re-sending the whole series). Using --in-reply-to makes it harder for
+to re-sending the whole series). Using ``--in-reply-to`` makes it harder for
reviewers to accidentally review old patches.
When submitting follow-up patches you should also login to
`patchwork <https://patchwork.freedesktop.org>`__ and change the state
of your old patches to Superseded.
-| Some companies' mail server automatically append a legal disclaimer,
- usually containing something along the lines of "The information in
- this email is confidential" and "distribution is strictly prohibited".
-| These legal notices prevent us from being able to accept your patch,
- rendering the whole process pointless. Please make sure these are
- disabled before sending your patches. (Note that you may need to
- contact your email administrator for this.)
+Some companies' mail server automatically append a legal disclaimer,
+usually containing something along the lines of "The information in
+this email is confidential" and "distribution is strictly prohibited".
+These legal notices prevent us from being able to accept your patch,
+rendering the whole process pointless. Please make sure these are
+disabled before sending your patches. (Note that you may need to
+contact your email administrator for this.)
Reviewing Patches
-----------------
@@ -182,13 +182,13 @@ Reviewing Patches
When you've reviewed a patch on the mailing list, please be unambiguous
about your review. That is, state either
-::
+.. code-block:: text
Reviewed-by: Joe Hacker <jhacker at foo.com>
or
-::
+.. code-block:: text
Acked-by: Joe Hacker <jhacker at foo.com>
@@ -196,7 +196,7 @@ Rather than saying just "LGTM" or "Seems OK".
If small changes are suggested, it's OK to say something like:
-::
+.. code-block:: text
With the above fixes, Reviewed-by: Joe Hacker <jhacker at foo.com>
@@ -214,8 +214,8 @@ branch and release.
mailing list.
- Forwarding the patch from the mesa-dev@ mailing list.
-Note: resending patch identical to one on mesa-dev@ or one that differs
-only by the extra mesa-stable@ tag is **not** recommended.
+ **Note**: resending patch identical to one on mesa-dev@ or one that differs
+ only by the extra mesa-stable@ tag is **not** recommended.
If you are not the author of the original patch, please Cc: them in your
nomination request.
@@ -235,13 +235,13 @@ nominate the commit for all the active stable branches. If the commit is
not applicable for said branch the stable-release manager will reply
stating so. This "CC" syntax for patch nomination will cause patches to
automatically be copied to the mesa-stable@ mailing list when you use
-"git send-email" to send patches to the mesa-dev@ mailing list. If you
-prefer using --suppress-cc that won't have any negative effect on the
+``git send-email`` to send patches to the mesa-dev@ mailing list. If you
+prefer using ``--suppress-cc`` that won't have any negative effect on the
patch nomination.
-| Note: by removing the tag [as the commit is pushed] the patch is
- **explicitly** rejected from inclusion in the stable branch(es).
-| Thus, drop the line **only** if you want to cancel the nomination.
+ **Note**: by removing the tag [as the commit is pushed] the patch is
+ **explicitly** rejected from inclusion in the stable branch(es).
+ Thus, drop the line **only** if you want to cancel the nomination.
Alternatively, if one uses the "Fixes" tag as described in the "Patch
formatting" section, it nominates a commit for all active stable
@@ -262,17 +262,22 @@ broad discretion in rejecting patches that have been nominated.
patch is too large and/or otherwise contradicts with the rules set
within, a backport is appropriate.
- It must not introduce a regression - be that build or runtime wise.
- Note: If the regression is due to faulty piglit/dEQP/CTS/other test
- the latter must be fixed first. A reference to the offending test(s)
- and respective fix(es) should be provided in the nominated patch.
+
+ **Note**: If the regression is due to faulty piglit/dEQP/CTS/other test
+ the latter must be fixed first. A reference to the offending test(s)
+ and respective fix(es) should be provided in the nominated patch.
+
- Patch cannot be larger than 100 lines.
- Patches that move code around with no functional change should be
rejected.
-- Patch must be a bug fix and not a new feature. Note: An exception to
- this rule, are hardware-enabling "features". For example,
- `backports <#backports>`__ of new code to support a newly-developed
- hardware product can be accepted if they can be reasonably determined
- not to have effects on other hardware.
+- Patch must be a bug fix and not a new feature.
+
+ **Note**: An exception to
+ this rule, are hardware-enabling "features". For example,
+ `backports <#backports>`__ of new code to support a newly-developed
+ hardware product can be accepted if they can be reasonably determined
+ not to have effects on other hardware.
+
- Patch must be reviewed, For example, the commit message has
Reviewed-by, Signed-off-by, or Tested-by tags from someone but the
author.
@@ -295,14 +300,14 @@ directly. Consider yourself warned.
Sending backports for the stable branch
---------------------------------------
-| By default merge conflicts are resolved by the stable-release manager.
- In which case he/she should provide a comment about the changes
- required, alongside the ``Conflicts`` section. Summary of which will
- be provided in the `pre-release <releasing.html#prerelease>`__
- announcement.
-| Developers are interested in sending backports are recommended to use
- either a ``[BACKPORT #branch]`` subject prefix or provides similar
- information within the commit summary.
+By default merge conflicts are resolved by the stable-release manager.
+In which case he/she should provide a comment about the changes
+required, alongside the ``Conflicts`` section. Summary of which will
+be provided in the `pre-release <releasing.html#prerelease>`__
+announcement.
+Developers are interested in sending backports are recommended to use
+either a ``[BACKPORT #branch]`` subject prefix or provides similar
+information within the commit summary.
Git tips
--------
@@ -310,7 +315,7 @@ Git tips
- ``git rebase -i ...`` is your friend. Don't be afraid to use it.
- Apply a fixup to commit FOO.
- ::
+ .. code-block:: bash
git add ...
git commit --fixup=FOO
@@ -318,27 +323,27 @@ Git tips
- Test for build breakage between patches e.g last 8 commits.
- ::
+ .. code-block:: bash
git rebase -i --exec="make -j4" HEAD~8
- Sets the default mailing address for your repo.
- ::
+ .. code-block:: bash
git config --local sendemail.to mesa-dev at lists.freedesktop.org
- Add version to subject line of patch series in this case for the last
8 commits before sending.
- ::
+ .. code-block:: bash
git send-email --subject-prefix="PATCH v4" HEAD~8
git send-email -v4 @~8 # shorter version, inherited from git format-patch
-- Configure git to use the get\_reviewer.pl script interactively. Thus
+- Configure git to use the ``get_reviewer.pl`` script interactively. Thus
you can avoid adding the world to the CC list.
- ::
+ .. code-block:: bash
git config sendemail.cccmd "./scripts/get_reviewer.pl -i"
diff --git a/docs/thanks.rst b/docs/thanks.rst
index 13669e740a..6860da6dd6 100644
--- a/docs/thanks.rst
+++ b/docs/thanks.rst
@@ -33,7 +33,7 @@ somewhat dated, unfortunately.
superceded by SGI SI GLU).
- **Holger Waechtler** contributed AMD 3DNow! assembly code which
accelerates vertex transformation in Mesa 3.1. Holger also
- implemented the GL\_EXT\_texture\_env\_combine extension.
+ implemented the ``GL_EXT_texture_env_combine`` extension.
- **Jeroen van der Zijp** and **Thorsten Ohl** contributed the Xt/Motif
widget code.
- **John Stone** provided the multi-threading support in Mesa 3.0.
diff --git a/docs/versions.rst b/docs/versions.rst
index 3d7ff94f5b..c284b547d5 100644
--- a/docs/versions.rst
+++ b/docs/versions.rst
@@ -1,5 +1,5 @@
-**NOTE: Changes for Mesa 6.4 and later are documented in the
-corresponding `release notes <relnotes.html>`__ file.**
+NOTE: Changes for Mesa 6.4 and later are documented in the
+corresponding `release notes <relnotes.html>`__ file.
Mesa Version History
====================
@@ -1673,5 +1673,5 @@ Bug fixes:
- fixed glxext.h cross-compile issue (Colin Harrison)
- assorted DRI driver fixes
-**NOTE: Changes for Mesa 6.4 and later are documented in the
-corresponding `release notes <relnotes.html>`__ file.**
+**NOTE**: Changes for Mesa 6.4 and later are documented in the
+corresponding `release notes <relnotes.html>`__ file.
diff --git a/docs/viewperf.rst b/docs/viewperf.rst
index b82a5e5c2c..3a2cb1f8d7 100644
--- a/docs/viewperf.rst
+++ b/docs/viewperf.rst
@@ -28,7 +28,7 @@ Catia-03 test 2
This test creates over 38000 vertex buffer objects. On some systems this
can exceed the maximum number of buffer allocations. Mesa generates
-GL\_OUT\_OF\_MEMORY errors in this situation, but Viewperf does no error
+``GL_OUT_OF_MEMORY`` errors in this situation, but Viewperf does no error
checking and continues. When this happens, some drawing commands become
no-ops. This can also eventually lead to a segfault either in Viewperf
or the Mesa driver.
@@ -65,7 +65,7 @@ sw-02 test 6
The lines drawn in this test appear in a random color. That's because
texture mapping is enabled when the lines are drawn, but no texture
-image is defined (glTexImage2D() is called with pixels=NULL). Since GL
+image is defined (``glTexImage2D()`` is called with ``pixels=NULL``). Since GL
says the contents of the texture image are undefined in that situation,
we get a random color.
@@ -80,7 +80,7 @@ A trace captured with `API
trace <https://github.com/apitrace/apitrace>`__ shows this sequences of
calls like this:
-::
+.. code-block:: c
2504 glBindTexture(target = GL_TEXTURE_2D, texture = 55)
2505 glTexImage2D(target = GL_TEXTURE_2D, level = 0, internalformat = GL_RGBA, width = 512, height = 512, border = 0, format = GL_RGB, type = GL_UNSIGNED_SHORT, pixels = blob(1572864))
@@ -94,11 +94,11 @@ calls like this:
2516 glTexParameteri(target = GL_TEXTURE_2D, pname = GL_TEXTURE_WRAP_T, param = GL_REPEAT)
2517 glTexParameteri(target = GL_TEXTURE_2D, pname = GL_TEXTURE_MAG_FILTER, param = GL_NEAREST)
-Note that one would expect call 2514 to be glTexImage(level=9, width=1,
-height=1) but it's not there.
+Note that one would expect call 2514 to be ``glTexImage(level=9, width=1,
+height=1)`` but it's not there.
-The minification filter is GL\_LINEAR\_MIPMAP\_LINEAR and the texture's
-GL\_TEXTURE\_MAX\_LEVEL is 1000 (the default) so a full mipmap is
+The minification filter is ``GL_LINEAR_MIPMAP_LINEAR`` and the texture's
+``GL_TEXTURE_MAX_LEVEL`` is 1000 (the default) so a full mipmap is
expected.
Later, these incomplete textures are bound before drawing calls.
@@ -112,7 +112,7 @@ case and returns (1,1,1,1) (white) which causes the rendering to appear
brighter and match the reference image (however, AMD's rendering is
*much* brighter than NVIDIA's).
-If the fallback texture created in \_mesa\_get\_fallback\_texture() is
+If the fallback texture created in ``_mesa_get_fallback_texture()`` is
initialized to be full white instead of full black the rendering appears
correct. However, we have no plans to implement this work-around in
Mesa.
@@ -120,35 +120,35 @@ Mesa.
Maya-03 test 2
~~~~~~~~~~~~~~
-This test makes some unusual calls to glRotate. For example:
+This test makes some unusual calls to ``glRotate``. For example:
-::
+.. code-block:: c
glRotate(50, 50, 50, 1);
glRotate(100, 100, 100, 1);
glRotate(52, 52, 52, 1);
These unusual values lead to invalid modelview matrices. For example,
-the last glRotate command above produces this matrix with Mesa:
+the last ``glRotate`` command above produces this matrix with Mesa:
-::
+.. code-block:: text
- 1.08536e+24 2.55321e-23 -0.000160389 0
- 5.96937e-25 1.08536e+24 103408 0
- 103408 -0.000160389 1.74755e+09 0
- 0 0 0 nan
+ 1.08536e+24 2.55321e-23 -0.000160389 0
+ 5.96937e-25 1.08536e+24 103408 0
+ 103408 -0.000160389 1.74755e+09 0
+ 0 0 0 nan
and with NVIDIA's OpenGL:
-::
+.. code-block:: text
- 1.4013e-45 0 -nan 0
- 0 1.4013e-45 1.4013e-45 0
- 1.4013e-45 -nan 1.4013e-45 0
- 0 0 0 1.4013e-45
+ 1.4013e-45 0 -nan 0
+ 0 1.4013e-45 1.4013e-45 0
+ 1.4013e-45 -nan 1.4013e-45 0
+ 0 0 0 1.4013e-45
This causes the object in question to be drawn in a strange orientation
-and with a semi-random color (between white and black) since GL\_FOG is
+and with a semi-random color (between white and black) since ``GL_FOG`` is
enabled.
Proe-05 test 1
@@ -156,8 +156,8 @@ Proe-05 test 1
This uses depth testing but there's two problems:
-#. The glXChooseFBConfig() call doesn't request a depth buffer
-#. The test never calls glClear(GL\_DEPTH\_BUFFER\_BIT) to initialize
+#. The ``glXChooseFBConfig()`` call doesn't request a depth buffer
+#. The test never calls ``glClear(GL_DEPTH_BUFFER_BIT)`` to initialize
the depth buffer
If the chosen visual does not have a depth buffer, you'll see the
@@ -171,10 +171,10 @@ buffer and apparently the contents are initialized to 1.0 by default so
this test just happens to work with their drivers.
Finally, even if a depth buffer was requested and the
-glClear(GL\_COLOR\_BUFFER\_BIT) calls were changed to
-glClear(GL\_COLOR\_BUFFER\_BIT \| GL\_DEPTH\_BUFFER\_BIT) the problem
-still wouldn't be fixed because GL\_DEPTH\_WRITEMASK=GL\_FALSE when
-glClear is called so clearing the depth buffer would be a no-op anyway.
+``glClear(GL_COLOR_BUFFER_BIT)`` calls were changed to
+``glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)`` the problem
+still wouldn't be fixed because ``GL_DEPTH_WRITEMASK=GL_FALSE`` when
+``glClear`` is called so clearing the depth buffer would be a no-op anyway.
Proe-05 test 6
~~~~~~~~~~~~~~
@@ -182,14 +182,14 @@ Proe-05 test 6
This test draws an engine model with a two-pass algorithm. The first
pass is drawn with polygon stipple enabled. The second pass is drawn
without polygon stipple but with blending and
-GL\_DEPTH\_FUNC=GL\_LEQUAL. If either of the two passes happen to use a
+``GL_DEPTH_FUNC=GL_LEQUAL``. If either of the two passes happen to use a
software fallback of some sort, the Z values of fragments may be
different between the two passes. This leads to incorrect rendering.
For example, the VMware SVGA gallium driver uses a special semi-fallback
path for drawing with polygon stipple. Since the two passes are rendered
with different vertex transformation implementations, the rendering
-doesn't appear as expected. Setting the SVGA\_FORCE\_SWTNL environment
+doesn't appear as expected. Setting the ``SVGA_FORCE_SWTNL`` environment
variable to 1 will force the driver to use the software vertex path all
the time and clears up this issue.
@@ -207,15 +207,15 @@ Note that Viewperf 12 only runs on 64-bit Windows 7 or later.
catia-04
~~~~~~~~
-One of the catia tests calls wglGetProcAddress() to get some
-GL\_EXT\_direct\_state\_access functions (such as glBindMultiTextureEXT)
-and some GL\_NV\_half\_float functions (such as glMultiTexCoord3hNV). If
-the extension/function is not supported, wglGetProcAddress() can return
+One of the catia tests calls ``wglGetProcAddress()`` to get some
+``GL_EXT_direct_state_access`` functions (such as ``glBindMultiTextureEXT``)
+and some ``GL_NV_half_float`` functions (such as ``glMultiTexCoord3hNV``). If
+the extension/function is not supported, ``wglGetProcAddress()`` can return
NULL. Unfortunately, Viewperf doesn't check for null pointers and
crashes when it later tries to use the pointer.
Another catia test uses OpenGL 3.1's primitive restart feature. But when
-Viewperf creates an OpenGL context, it doesn't request version 3.1 If
+Viewperf creates an OpenGL context, it doesn't request version 3.1. If
the driver returns version 3.0 or earlier all the calls related to
primitive restart generate an OpenGL error. Some of the rendering is
then incorrect.
@@ -225,26 +225,26 @@ energy-01
This test creates a 3D luminance texture of size 1K x 1K x 1K. If the
OpenGL driver/device doesn't support a texture of this size the
-glTexImage3D() call will fail with GL\_INVALID\_VALUE or
-GL\_OUT\_OF\_MEMORY and all that's rendered is plain white polygons.
+``glTexImage3D()`` call will fail with ``GL_INVALID_VALUE`` or
+``GL_OUT_OF_MEMORY`` and all that's rendered is plain white polygons.
Ideally, the test would use a proxy texture to determine the max 3D
texture size. But it does not do that.
maya-04
~~~~~~~
-This test generates many GL\_INVALID\_OPERATION errors in its calls to
-glUniform(). Causes include:
+This test generates many ``GL_INVALID_OPERATION`` errors in its calls to
+``glUniform()``. Causes include:
-- Trying to set float uniforms with glUniformi()
-- Trying to set float uniforms with glUniform3f()
-- Trying to set matrix uniforms with glUniform() instead of
- glUniformMatrix().
+- Trying to set float uniforms with ``glUniformi()``
+- Trying to set float uniforms with ``glUniform3f()``
+- Trying to set matrix uniforms with ``glUniform()`` instead of
+ ``glUniformMatrix()``.
-Apparently, the indexes returned by glGetUniformLocation() were
+Apparently, the indexes returned by ``glGetUniformLocation()`` were
hard-coded into the application trace when it was created. Since
-different implementations of glGetUniformLocation() may return different
-values for any given uniform name, subsequent calls to glUniform() will
+different implementations of ``glGetUniformLocation()`` may return different
+values for any given uniform name, subsequent calls to ``glUniform()`` will
be invalid since they refer to the wrong uniform variables. This causes
many OpenGL errors and leads to incorrect rendering.
@@ -257,7 +257,7 @@ at the top of the shader code. So, the shader does not compile and all
that's rendered is plain white polygons.
Also, the test tries to create a very large 3D texture that may exceed
-the device driver's limit. When this happens, the glTexImage3D call
+the device driver's limit. When this happens, the ``glTexImage3D`` call
fails and all that's rendered is a white box.
showcase-01
diff --git a/docs/vmware-guest.rst b/docs/vmware-guest.rst
index 19b8bfc915..092fdd57e8 100644
--- a/docs/vmware-guest.rst
+++ b/docs/vmware-guest.rst
@@ -20,7 +20,7 @@ supported in the guest. This requires:
Otherwise, OpenGL 2.1 is supported.
OpenGL 3.3 support can be disabled by setting the environment variable
-SVGA\_VGPU10=0. You will then have OpenGL 2.1 support. This may be
+``SVGA_VGPU10=0``. You will then have OpenGL 2.1 support. This may be
useful to work around application bugs (such as incorrect use of the
OpenGL 3.x core profile).
@@ -59,25 +59,25 @@ Prerequisites
- Ubuntu: For ubuntu you need to install a number of build
dependencies.
- ::
+ .. code-block:: bash
sudo apt-get install git-core
sudo apt-get install automake libtool libpthread-stubs0-dev
sudo apt-get install xserver-xorg-dev x11proto-xinerama-dev libx11-xcb-dev
sudo apt-get install libxcb-glx0-dev libxrender-dev
sudo apt-get build-dep libgl1-mesa-dri libxcb-glx0-dev
-
+
- Fedora: For Fedora you also need to install a number of build
dependencies.
- ::
+ .. code-block:: bash
sudo yum install mesa-libGL-devel xorg-x11-server-devel xorg-x11-util-macros
sudo yum install libXrender-devel.i686
sudo yum install automake gcc libtool expat-devel kernel-devel git-core
sudo yum install makedepend flex bison
-
+
Depending on your Linux distro, other packages may be needed. The
configure scripts should tell you what's missing.
@@ -87,179 +87,179 @@ Getting the Latest Source Code
Begin by saving your current directory location:
-::
+.. code-block:: bash
export TOP=$PWD
-
+
- Mesa/Gallium master branch. This code is used to build libGL, and the
direct rendering svga driver for libGL, vmwgfx\_dri.so, and the X
acceleration library libxatracker.so.x.x.x.
- ::
+ .. code-block:: bash
git clone git://anongit.freedesktop.org/git/mesa/mesa
-
+
- VMware Linux guest kernel module. Note that this repo contains the
complete DRM and TTM code. The vmware-specific driver is really only
the files prefixed with vmwgfx.
- ::
+ .. code-block:: bash
git clone git://anongit.freedesktop.org/git/mesa/vmwgfx
-
+
- libdrm, a user-space library that interfaces with drm. Most distros
ship with this but it's safest to install a newer version. To get the
latest code from git:
- ::
+ .. code-block:: bash
git clone git://anongit.freedesktop.org/git/mesa/drm
-
+
- xf86-video-vmware. The chainloading driver, vmware\_drv.so, the
legacy driver vmwlegacy\_drv.so, and the vmwgfx driver
vmwgfx\_drv.so.
- ::
+ .. code-block:: bash
git clone git://anongit.freedesktop.org/git/xorg/driver/xf86-video-vmware
-
+
Building the Code
-----------------
-- | Determine where the GL-related libraries reside on your system and
- set the LIBDIR environment variable accordingly.
- | For 32-bit Ubuntu systems:
+- Determine where the GL-related libraries reside on your system and
+ set the LIBDIR environment variable accordingly.
+
+ For 32-bit Ubuntu systems:
- ::
+ .. code-block:: bash
export LIBDIR=/usr/lib/i386-linux-gnu
For 64-bit Ubuntu systems:
- ::
+ .. code-block:: bash
export LIBDIR=/usr/lib/x86_64-linux-gnu
For 32-bit Fedora systems:
- ::
+ .. code-block:: bash
export LIBDIR=/usr/lib
For 64-bit Fedora systems:
- ::
+ .. code-block:: bash
export LIBDIR=/usr/lib64
- Build libdrm:
- ::
+ .. code-block:: bash
cd $TOP/drm
./autogen.sh --prefix=/usr --libdir=${LIBDIR}
make
sudo make install
-
-- | Build Mesa and the vmwgfx\_dri.so driver, the vmwgfx\_drv.so xorg
- driver, the X acceleration library libxatracker. The vmwgfx\_dri.so
- is used by the OpenGL libraries during direct rendering, and by the
- Xorg server during accelerated indirect GL rendering. The
- libxatracker library is used exclusively by the X server to do
- render, copy and video acceleration:
- | The following configure options doesn't build the EGL system.
- ::
+- Build Mesa and the vmwgfx\_dri.so driver, the vmwgfx\_drv.so xorg
+ driver, the X acceleration library libxatracker. The vmwgfx\_dri.so
+ is used by the OpenGL libraries during direct rendering, and by the
+ Xorg server during accelerated indirect GL rendering. The
+ libxatracker library is used exclusively by the X server to do
+ render, copy and video acceleration:
+ The following configure options doesn't build the EGL system.
+
+ .. code-block:: bash
cd $TOP/mesa
./autogen.sh --prefix=/usr --libdir=${LIBDIR} --with-gallium-drivers=svga --with-dri-drivers=swrast --enable-xa --disable-dri3 --enable-glx-tls
make
sudo make install
-
- | Note that you may have to install other packages that Mesa depends
- upon if they're not installed in your system. You should be told
- what's missing.
+ Note that you may have to install other packages that Mesa depends
+ upon if they're not installed in your system. You should be told
+ what's missing.
- xf86-video-vmware: Now, once libxatracker is installed, we proceed
with building and replacing the current Xorg driver. First check if
your system is 32- or 64-bit.
- ::
+ .. code-block:: bash
cd $TOP/xf86-video-vmware
./autogen.sh --prefix=/usr --libdir=${LIBDIR}
make
sudo make install
-
+
- vmwgfx kernel module. First make sure that any old version of this
kernel module is removed from the system by issuing
- ::
+ .. code-block:: text
- sudo rm /lib/modules/`uname -r`/kernel/drivers/gpu/drm/vmwgfx.ko*
+ sudo rm /lib/modules/`uname -r`/kernel/drivers/gpu/drm/vmwgfx.ko*
- Build and install:
+ Build and install:
- ::
+ .. code-block:: bash
- cd $TOP/vmwgfx
- make
- sudo make install
- sudo depmod -a
+ cd $TOP/vmwgfx
+ make
+ sudo make install
+ sudo depmod -a
- If you're using a Ubuntu OS:
+ If you're using a Ubuntu OS:
- ::
+ .. code-block:: bash
- sudo update-initramfs -u
+ sudo update-initramfs -u
- If you're using a Fedora OS:
+ If you're using a Fedora OS:
- ::
+ .. code-block:: bash
- sudo dracut --force
+ sudo dracut --force
- Add 'vmwgfx' to the /etc/modules file:
+ Add 'vmwgfx' to the /etc/modules file:
- ::
+ .. code-block:: bash
- echo vmwgfx | sudo tee -a /etc/modules
+ echo vmwgfx | sudo tee -a /etc/modules
- Note: some distros put DRM kernel drivers in different directories.
- For example, sometimes vmwgfx.ko might be found in
- ``/lib/modules/{version}/extra/vmwgfx.ko`` or in
- ``/lib/modules/{version}/kernel/drivers/gpu/drm/vmwgfx/vmwgfx.ko``.
+**Note**: some distros put DRM kernel drivers in different directories.
+For example, sometimes vmwgfx.ko might be found in
+``/lib/modules/{version}/extra/vmwgfx.ko`` or in
+``/lib/modules/{version}/kernel/drivers/gpu/drm/vmwgfx/vmwgfx.ko``.
- After installing vmwgfx.ko you might want to run the following
- command to check that the new kernel module is in the expected place:
+ After installing vmwgfx.ko you might want to run the following
+ command to check that the new kernel module is in the expected place:
- ::
+ .. code-block:: bash
- find /lib/modules -name vmwgfx.ko -exec ls -l '{}' \;
+ find /lib/modules -name vmwgfx.ko -exec ls -l '{}' \;
- If you see the kernel module listed in more than one place, you may
- need to move things around.
+ If you see the kernel module listed in more than one place, you may
+ need to move things around.
- Finally, if you update your kernel you'll probably have to rebuild
- and reinstall the vmwgfx.ko module again.
+ Finally, if you update your kernel you'll probably have to rebuild
+ and reinstall the vmwgfx.ko module again.
Now try to load the kernel module by issuing
-::
+.. code-block:: bash
sudo modprobe vmwgfx
Then type
-::
+.. code-block:: bash
dmesg
@@ -274,10 +274,10 @@ Xorg driver is in use.
Running OpenGL Programs
-----------------------
-In a shell, run 'glxinfo' and look for the following to verify that the
+In a shell, run ``glxinfo`` and look for the following to verify that the
driver is working:
-::
+.. code-block:: text
OpenGL vendor string: VMware, Inc.
OpenGL renderer string: Gallium 0.4 on SVGA3D; build: RELEASE;
@@ -285,7 +285,7 @@ driver is working:
If you don't see this, try setting this environment variable:
-::
+.. code-block:: bash
export LIBGL_DEBUG=verbose
@@ -296,4 +296,4 @@ If OpenGL 3.3 is not working (you only get OpenGL 2.1):
- Make sure the VM uses hardware version 12.
- Make sure the vmwgfx kernel module is version 2.9.0 or later.
- Check the vmware.log file for errors.
-- Run 'dmesg \| grep vmwgfx' and look for "DX: yes".
+- Run ``dmesg | grep vmwgfx`` and look for "DX: yes".
diff --git a/docs/xlibdriver.rst b/docs/xlibdriver.rst
index 2f52fe6d72..d1d5a20b1f 100644
--- a/docs/xlibdriver.rst
+++ b/docs/xlibdriver.rst
@@ -20,21 +20,21 @@ X Visual Selection
Mesa supports RGB(A) rendering into almost any X visual type and depth.
-The glXChooseVisual function tries to choose the best X visual for the
+The ``glXChooseVisual`` function tries to choose the best X visual for the
given attribute list. However, if this doesn't suit your needs you can
force Mesa to use any X visual you want (any supported by your X server
-that is) by setting the **MESA\_RGB\_VISUAL** and **MESA\_CI\_VISUAL**
-environment variables. When an RGB visual is requested, glXChooseVisual
-will first look if the MESA\_RGB\_VISUAL variable is defined. If so, it
+that is) by setting the ``MESA_RGB_VISUAL`` and ``MESA_CI_VISUAL``
+environment variables. When an RGB visual is requested, ``glXChooseVisual``
+will first look if the ``MESA_RGB_VISUAL`` variable is defined. If so, it
will try to use the specified visual. Similarly, when a color index
-visual is requested, glXChooseVisual will look for the MESA\_CI\_VISUAL
+visual is requested, ``glXChooseVisual`` will look for the ``MESA_CI_VISUAL``
variable.
The format of accepted values is: ``visual-class depth``
Here are some examples:
-::
+.. code-block:: text
using csh:
% setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor
@@ -51,20 +51,20 @@ Double Buffering
Mesa can use either an X Pixmap or XImage as the back color buffer when
in double-buffer mode. The default is to use an XImage. The
-**MESA\_BACK\_BUFFER** environment variable can override this. The valid
-values for **MESA\_BACK\_BUFFER** are: **Pixmap** and **XImage** (only
+``MESA_BACK_BUFFER`` environment variable can override this. The valid
+values for ``MESA_BACK_BUFFER`` are: ``Pixmap`` and ``XImage`` (only
the first letter is checked, case doesn't matter).
Using XImage is almost always faster than a Pixmap since it resides in
-the application's address space. When glXSwapBuffers() is called,
-XPutImage() or XShmPutImage() is used to transfer the XImage to the
+the application's address space. When ``glXSwapBuffers()`` is called,
+``XPutImage()`` or ``XShmPutImage()`` is used to transfer the XImage to the
on-screen window.
A Pixmap may be faster when doing remote rendering of a simple scene.
Some OpenGL features will be very slow with a Pixmap (for example,
blending will require a round-trip message for pixel readback.)
-Experiment with the MESA\_BACK\_BUFFER variable to see which is faster
+Experiment with the ``MESA_BACK_BUFFER`` variable to see which is faster
for your application.
Colormaps
@@ -80,7 +80,7 @@ window. Otherwise, a new, private colormap will be allocated.
When sharing the root colormap, Mesa may be unable to allocate the
colors it needs, resulting in poor color quality. This can happen when a
large number of colorcells in the root colormap are already allocated.
-To prevent colormap sharing in GLUT, set the **MESA\_PRIVATE\_CMAP**
+To prevent colormap sharing in GLUT, set the ``MESA_PRIVATE_CMAP``
environment variable. The value isn't significant.
Gamma Correction
@@ -93,17 +93,17 @@ systems, such as Silicon Graphics, support gamma correction in hardware
systems, however, may need gamma adjustment to produce images which look
correct. If you believe that Mesa's images are too dim, read on.
-Gamma correction is controlled with the **MESA\_GAMMA** environment
+Gamma correction is controlled with the ``MESA_GAMMA`` environment
variable. Its value is of the form **Gr Gg Gb** or just **G** where Gr
is the red gamma value, Gg is the green gamma value, Gb is the blue
gamma value and G is one gamma value to use for all three channels. Each
value is a positive real number typically in the range 1.0 to 2.5. The
defaults are all 1.0, effectively disabling gamma correction. Examples:
-::
+.. code-block:: bash
% export MESA_GAMMA="2.3 2.2 2.4" // separate R,G,B values
- % export MESA_GAMMA="2.0" // same gamma for R,G,B
+ % export MESA_GAMMA="2.0" // same gamma for R,G,B
The ``demos/gamma.c`` program in mesa/demos repository may help you to
determine reasonable gamma value for your display. With correct gamma
@@ -117,8 +117,8 @@ Mesa implements gamma correction with a lookup table which translates a
"linear" pixel value to a gamma-corrected pixel value. There is a small
performance penalty. Gamma correction only works in RGB mode. Also be
aware that pixel values read back from the frame buffer will not be
-"un-corrected" so glReadPixels may not return the same data drawn with
-glDrawPixels.
+"un-corrected" so ``glReadPixels`` may not return the same data drawn with
+``glDrawPixels``.
For more information about gamma correction, see the `Wikipedia
article <https://en.wikipedia.org/wiki/Gamma_correction>`__
@@ -128,16 +128,16 @@ Overlay Planes
Hardware overlay planes are supported by the Xlib driver. To determine
if your X server has overlay support you can test for the
-SERVER\_OVERLAY\_VISUALS property:
+``SERVER_OVERLAY_VISUALS`` property:
-::
+.. code-block:: bash
xprop -root | grep SERVER_OVERLAY_VISUALS
HPCR Dithering
--------------
-If you set the **MESA\_HPCR\_CLEAR** environment variable then dithering
+If you set the ``MESA_HPCR_CLEAR`` environment variable then dithering
will be used when clearing the color buffer. This is only applicable to
HP systems with the HPCR (Color Recovery) feature. This incurs a small
performance penalty.
@@ -153,12 +153,12 @@ GLX\_MESA\_pixmap\_colormap
This extension adds the GLX function:
-::
+.. code-block:: c
GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
Pixmap pixmap, Colormap cmap )
-It is an alternative to the standard glXCreateGLXPixmap() function.
+It is an alternative to the standard ``glXCreateGLXPixmap()`` function.
Since Mesa supports RGB rendering into any X visual, not just True-
Color or DirectColor, Mesa needs colormap information to convert RGB
values into pixel values. An X window carries this information but a
@@ -175,18 +175,18 @@ GLX\_MESA\_release\_buffers
Mesa associates a set of ancillary (depth, accumulation, stencil and
alpha) buffers with each X window it draws into. These ancillary buffers
are allocated for each X window the first time the X window is passed to
-glXMakeCurrent(). Mesa, however, can't detect when an X window has been
+``glXMakeCurrent()``. Mesa, however, can't detect when an X window has been
destroyed in order to free the ancillary buffers.
The best it can do is to check for recently destroyed windows whenever
-the client calls the glXCreateContext() or glXDestroyContext()
+the client calls the ``glXCreateContext()`` or ``glXDestroyContext()``
functions. This may not be sufficient in all situations though.
-The GLX\_MESA\_release\_buffers extension allows a client to explicitly
-deallocate the ancillary buffers by calling glxReleaseBuffersMESA() just
+The ``GLX_MESA_release_buffers`` extension allows a client to explicitly
+deallocate the ancillary buffers by calling ``glxReleaseBuffersMESA()`` just
before an X window is destroyed. For example:
-::
+.. code-block:: c
#ifdef GLX_MESA_release_buffers
glXReleaseBuffersMESA( dpy, window );
@@ -201,8 +201,8 @@ This extension was added in Mesa 2.0.
GLX\_MESA\_copy\_sub\_buffer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This extension adds the glXCopySubBufferMESA() function. It works like
-glXSwapBuffers() but only copies a sub-region of the window instead of
+This extension adds the ``glXCopySubBufferMESA()`` function. It works like
+``glXSwapBuffers()`` but only copies a sub-region of the window instead of
the whole window.
`GLX\_MESA\_copy\_sub\_buffer
@@ -213,7 +213,7 @@ This extension was added in Mesa 2.6
Summary of X-related environment variables
------------------------------------------
-::
+.. code-block:: text
MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
--
2.14.3
More information about the mesa-dev
mailing list