diff options
| author | Laura Ekstrand <laura@jlekstrand.net> | 2018-05-18 16:31:47 -0700 |
|---|---|---|
| committer | Laura Ekstrand <laura@jlekstrand.net> | 2018-06-15 16:07:20 -0700 |
| commit | 38c9af4d7355fa93753c3db6cda16cd7b231b28b (patch) | |
| tree | 90ab0f07638f284cb1634dfcb576cf248f972646 | |
| parent | 25f7230f6e9075c47a146f172a674abe8120c5bc (diff) | |
docs: Human edits to the website code for clarity.
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.
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 36ef3274a9..266d9b33f4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,7 +100,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 7d0f80059b..20cbc3da1f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -127,11 +127,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 -------------- @@ -185,11 +186,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 ----------------- @@ -243,11 +245,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 ------------------ @@ -313,11 +316,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 ------------ @@ -359,12 +363,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 ------------- @@ -394,12 +399,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 --------------- @@ -410,11 +416,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 ----------------- @@ -466,12 +473,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 -------------- @@ -496,11 +504,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 ---------------- @@ -559,11 +568,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 ------------------ @@ -629,11 +639,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 ------------- @@ -736,12 +747,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 ----------------- @@ -784,12 +796,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 ------------------ @@ -892,12 +905,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 -------------- @@ -1357,7 +1371,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 @@ -1372,7 +1386,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 @@ -1411,7 +1425,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 @@ -1426,7 +1440,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 @@ -1445,7 +1459,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 @@ -1460,7 +1474,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) @@ -1483,7 +1497,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 @@ -1498,7 +1512,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 @@ -1537,7 +1551,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 @@ -1552,7 +1566,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 @@ -1587,7 +1601,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 @@ -1602,7 +1616,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 @@ -1635,7 +1649,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 @@ -1677,7 +1691,7 @@ features. The MD5 checksums are: -:: +.. code-block:: bash 78f452f6c55478471a744f07147612b5 MesaLib-5.1.tar.gz 67b3b8d3f7f4c8c44904551b851d01af MesaLib-5.1.tar.bz2 @@ -1694,7 +1708,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 @@ -1708,7 +1722,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) @@ -1751,7 +1765,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 @@ -1790,7 +1804,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 @@ -1815,7 +1829,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") @@ -1845,7 +1859,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 @@ -1902,7 +1916,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 @@ -1936,7 +1950,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) @@ -1969,7 +1983,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 @@ -1999,7 +2013,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) @@ -2032,7 +2046,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 @@ -2067,7 +2081,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) @@ -2112,7 +2126,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 @@ -2140,15 +2154,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 @@ -2180,7 +2194,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) @@ -2213,7 +2227,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 @@ -2239,7 +2253,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 @@ -2276,9 +2290,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 @@ -2379,7 +2393,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@... @@ -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@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@foo.com> Acked-by: Joe Hacker <jhacker@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@foo.com> or -:: +.. code-block:: text Acked-by: Joe Hacker <jhacker@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@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@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) |