Mesa (main): docs: use envvar role for envvars
GitLab Mirror
gitlab-mirror at kemper.freedesktop.org
Wed Jun 2 12:59:33 UTC 2021
Module: Mesa
Branch: main
Commit: d4397c00485d8edb35d519e7036405527bb3e746
URL: http://cgit.freedesktop.org/mesa/mesa/commit/?id=d4397c00485d8edb35d519e7036405527bb3e746
Author: Erik Faye-Lund <erik.faye-lund at collabora.com>
Date: Tue Jun 1 11:30:08 2021 +0200
docs: use envvar role for envvars
Reviewed-by: Chia-I Wu <olvaffe at gmail.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11106>
---
docs/envvars.rst | 214 ++++++++++++++++++++++++++++---------------------------
1 file changed, 108 insertions(+), 106 deletions(-)
diff --git a/docs/envvars.rst b/docs/envvars.rst
index 46595e78006..20e090e7f9c 100644
--- a/docs/envvars.rst
+++ b/docs/envvars.rst
@@ -8,49 +8,49 @@ but they can sometimes be useful for debugging end-user issues.
LibGL environment variables
---------------------------
-``LIBGL_DEBUG``
+:envvar:`LIBGL_DEBUG`
If defined debug information will be printed to stderr. If set to
``verbose`` additional information will be printed.
-``LIBGL_DRIVERS_PATH``
+:envvar:`LIBGL_DRIVERS_PATH`
colon-separated list of paths to search for DRI drivers
-``LIBGL_ALWAYS_INDIRECT``
+:envvar:`LIBGL_ALWAYS_INDIRECT`
if set to ``true``, forces an indirect rendering context/connection.
-``LIBGL_ALWAYS_SOFTWARE``
+:envvar:`LIBGL_ALWAYS_SOFTWARE`
if set to ``true``, always use software rendering
-``LIBGL_NO_DRAWARRAYS``
+:envvar:`LIBGL_NO_DRAWARRAYS`
if set to ``true``, do not use DrawArrays GLX protocol (for
debugging)
-``LIBGL_SHOW_FPS``
+:envvar:`LIBGL_SHOW_FPS`
print framerate to stdout based on the number of ``glXSwapBuffers``
calls per second.
-``LIBGL_DRI2_DISABLE``
+:envvar:`LIBGL_DRI2_DISABLE`
disable DRI2 if set to ``true``.
-``LIBGL_DRI3_DISABLE``
+:envvar:`LIBGL_DRI3_DISABLE`
disable DRI3 if set to ``true``.
Core Mesa environment variables
-------------------------------
-``MESA_NO_ASM``
+:envvar:`MESA_NO_ASM`
if set, disables all assembly language optimizations
-``MESA_NO_MMX``
+:envvar:`MESA_NO_MMX`
if set, disables Intel MMX optimizations
-``MESA_NO_3DNOW``
+:envvar:`MESA_NO_3DNOW`
if set, disables AMD 3DNow! optimizations
-``MESA_NO_SSE``
+:envvar:`MESA_NO_SSE`
if set, disables Intel SSE optimizations
-``MESA_NO_ERROR``
+:envvar:`MESA_NO_ERROR`
if set to 1, error checking is disabled as per ``KHR_no_error``. This
will result in undefined behavior for invalid use of the API, but
can reduce CPU use for apps that are known to be error free.
-``MESA_DEBUG``
+:envvar:`MESA_DEBUG`
if set, error messages are printed to stderr. For example, if the
application generates a ``GL_INVALID_ENUM`` error, a corresponding
error message indicating where the error occurred, and possibly why,
- will be printed to stderr. For release builds, ``MESA_DEBUG``
- defaults to off (no debug output). ``MESA_DEBUG`` accepts the
+ will be printed to stderr. For release builds, :envvar:`MESA_DEBUG`
+ defaults to off (no debug output). :envvar:`MESA_DEBUG` accepts the
following comma-separated list of named flags, which adds extra
- behavior to just set ``MESA_DEBUG=1``:
+ behavior to just set :envvar:`MESA_DEBUG` to ``1``:
``silent``
turn off debug messages. Only useful for debug builds.
@@ -65,21 +65,21 @@ Core Mesa environment variables
print error and performance messages to stderr (or
``MESA_LOG_FILE``).
-``MESA_LOG_FILE``
+:envvar:`MESA_LOG_FILE`
specifies a file name for logging all errors, warnings, etc., rather
than stderr
-``MESA_TEX_PROG``
+:envvar:`MESA_TEX_PROG`
if set, implement conventional texture environment modes with fragment
programs (intended for developers only)
-``MESA_TNL_PROG``
+:envvar:`MESA_TNL_PROG`
if set, implement conventional vertex transformation operations with
vertex programs (intended for developers only). Setting this variable
- automatically sets the ``MESA_TEX_PROG`` variable as well.
-``MESA_EXTENSION_OVERRIDE``
+ automatically sets the :envvar:`MESA_TEX_PROG` variable as well.
+:envvar:`MESA_EXTENSION_OVERRIDE`
can be used to enable/disable extensions. A value such as
``GL_EXT_foo -GL_EXT_bar`` will enable the ``GL_EXT_foo`` extension
and disable the ``GL_EXT_bar`` extension.
-``MESA_EXTENSION_MAX_YEAR``
+:envvar:`MESA_EXTENSION_MAX_YEAR`
The ``GL_EXTENSIONS`` string returned by Mesa is sorted by extension
year. If this variable is set to year X, only extensions defined on
or before year X will be reported. This is to work-around a bug in
@@ -87,7 +87,7 @@ Core Mesa environment variables
buffer without truncating. If the extension string is too long, the
buffer overrun can cause the game to crash. This is a work-around for
that.
-``MESA_GL_VERSION_OVERRIDE``
+:envvar:`MESA_GL_VERSION_OVERRIDE`
changes the value returned by ``glGetString(GL_VERSION)`` and
possibly the GL API type.
@@ -127,7 +127,7 @@ Core Mesa environment variables
- Mesa may not really implement all the features of the given
version. (for developers only)
-``MESA_GLES_VERSION_OVERRIDE``
+:envvar:`MESA_GLES_VERSION_OVERRIDE`
changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL
ES.
@@ -136,17 +136,17 @@ Core Mesa environment variables
- Mesa may not really implement all the features of the given
version. (for developers only)
-``MESA_GLSL_VERSION_OVERRIDE``
+:envvar:`MESA_GLSL_VERSION_OVERRIDE`
changes the value returned by
``glGetString(GL_SHADING_LANGUAGE_VERSION)``. Valid values are
integers, such as ``130``. Mesa will not really implement all the
features of the given language version if it's higher than what's
normally reported. (for developers only)
-``MESA_GLSL_CACHE_DISABLE``
+:envvar:`MESA_GLSL_CACHE_DISABLE`
if set to ``true``, disables the GLSL shader cache. If set to
``false``, enables the GLSL shader cache when it is disabled by
default.
-``MESA_GLSL_CACHE_MAX_SIZE``
+:envvar:`MESA_GLSL_CACHE_MAX_SIZE`
if set, determines the maximum size of the on-disk cache of compiled
GLSL programs. Should be set to a number optionally followed by
``K``, ``M``, or ``G`` to specify a size in kilobytes, megabytes, or
@@ -160,22 +160,22 @@ Core Mesa environment variables
you may end up with a 1GB cache for x86_64 and another 1GB cache for
i386.
-``MESA_GLSL_CACHE_DIR``
+:envvar:`MESA_GLSL_CACHE_DIR`
if set, determines the directory to be used for the on-disk cache of
compiled GLSL programs. If this variable is not set, then the cache
will be stored in ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that
variable is set), or else within ``.cache/mesa_shader_cache`` within
the user's home directory.
-``MESA_GLSL``
+:envvar:`MESA_GLSL`
:ref:`shading language compiler options <envvars>`
-``MESA_NO_MINMAX_CACHE``
+:envvar:`MESA_NO_MINMAX_CACHE`
when set, the minmax index cache is globally disabled.
-``MESA_SHADER_CAPTURE_PATH``
+:envvar:`MESA_SHADER_CAPTURE_PATH`
see :ref:`Capturing Shaders <capture>`
-``MESA_SHADER_DUMP_PATH`` and ``MESA_SHADER_READ_PATH``
+:envvar:`MESA_SHADER_DUMP_PATH` and :envvar:`MESA_SHADER_READ_PATH`
see :ref:`Experimenting with Shader
Replacements <replacement>`
-``MESA_VK_VERSION_OVERRIDE``
+:envvar:`MESA_VK_VERSION_OVERRIDE`
changes the Vulkan physical device version as returned in
``VkPhysicalDeviceProperties::apiVersion``.
@@ -184,7 +184,7 @@ Core Mesa environment variables
instance version as advertised by ``vkEnumerateInstanceVersion``
- This can be very useful for debugging but some features may not be
implemented correctly. (For developers only)
-``MESA_LOADER_DRIVER_OVERRIDE``
+:envvar:`MESA_LOADER_DRIVER_OVERRIDE`
chooses a different driver binary such as ``etnaviv`` or ``zink``.
NIR passes environment variables
@@ -194,13 +194,13 @@ The following are only applicable for drivers that uses NIR, as they
modify the behavior for the common ``NIR_PASS`` and ``NIR_PASS_V`` macros,
that wrap calls to NIR lowering/optimizations.
-``NIR_PRINT``
+:envvar:`NIR_PRINT`
If defined, the resulting NIR shader will be printed out at each
successful NIR lowering/optimization call.
-``NIR_TEST_CLONE``
+:envvar:`NIR_TEST_CLONE`
If defined, cloning a NIR shader would be tested at each successful
NIR lowering/optimization call.
-``NIR_TEST_SERIALIZE``
+:envvar:`NIR_TEST_SERIALIZE`
If defined, serialize and deserialize a NIR shader would be tested at
each successful NIR lowering/optimization call.
@@ -210,31 +210,31 @@ Mesa Xlib driver environment variables
The following are only applicable to the Mesa Xlib software driver. See
the :doc:`Xlib software driver page <xlibdriver>` for details.
-``MESA_RGB_VISUAL``
+:envvar:`MESA_RGB_VISUAL`
specifies the X visual and depth for RGB mode
-``MESA_BACK_BUFFER``
+:envvar:`MESA_BACK_BUFFER`
specifies how to implement the back color buffer, either ``pixmap``
or ``ximage``
-``MESA_GAMMA``
+:envvar:`MESA_GAMMA`
gamma correction coefficients for red, green, blue channels
-``MESA_XSYNC``
+:envvar:`MESA_XSYNC`
enable synchronous X behavior (for debugging only)
-``MESA_GLX_FORCE_CI``
+:envvar:`MESA_GLX_FORCE_CI`
if set, force GLX to treat 8 BPP visuals as CI visuals
-``MESA_GLX_FORCE_ALPHA``
+:envvar:`MESA_GLX_FORCE_ALPHA`
if set, forces RGB windows to have an alpha channel.
-``MESA_GLX_DEPTH_BITS``
+:envvar:`MESA_GLX_DEPTH_BITS`
specifies default number of bits for depth buffer.
-``MESA_GLX_ALPHA_BITS``
+:envvar:`MESA_GLX_ALPHA_BITS`
specifies default number of bits for alpha channel.
i945/i965 driver environment variables (non-Gallium)
----------------------------------------------------
-``INTEL_NO_HW``
+:envvar:`INTEL_NO_HW`
if set to 1, prevents batches from being submitted to the hardware.
This is useful for debugging hangs, etc.
-``INTEL_DEBUG``
+:envvar:`INTEL_DEBUG`
a comma-separated list of named flags, which do various things:
``ann``
@@ -330,26 +330,26 @@ i945/i965 driver environment variables (non-Gallium)
``vs``
dump shader assembly for vertex shaders
-``INTEL_SCALAR_VS`` (or ``TCS``, ``TES``, ``GS``)
+:envvar:`INTEL_SCALAR_VS` (or ``TCS``, ``TES``, ``GS``)
force scalar/vec4 mode for a shader stage (Gen8-9 only)
-``INTEL_PRECISE_TRIG``
+:envvar:`INTEL_PRECISE_TRIG`
if set to 1, true or yes, then the driver prefers accuracy over
performance in trig functions.
-``INTEL_SHADER_ASM_READ_PATH``
+:envvar:`INTEL_SHADER_ASM_READ_PATH`
if set, determines the directory to be used for overriding shader
assembly. The binaries with custom assembly should be placed in
this folder and have a name formatted as ``sha1_of_assembly.bin``.
The sha1 of a shader assembly is printed when assembly is dumped via
- corresponding ``INTEL_DEBUG`` flag (e.g. ``vs`` for vertex shader).
+ corresponding :envvar:`INTEL_DEBUG` flag (e.g. ``vs`` for vertex shader).
A binary could be generated from a dumped assembly by ``i965_asm``.
- For ``INTEL_SHADER_ASM_READ_PATH`` to work it is necessary to enable
- dumping of corresponding shader stages via ``INTEL_DEBUG``.
- It is advised to use ``nocompact`` flag of ``INTEL_DEBUG`` when
+ For :envvar:`INTEL_SHADER_ASM_READ_PATH` to work it is necessary to enable
+ dumping of corresponding shader stages via :envvar:`INTEL_DEBUG`.
+ It is advised to use ``nocompact`` flag of :envvar:`INTEL_DEBUG` when
dumping and overriding shader assemblies.
The success of assembly override would be signified by "Successfully
overrode shader with sha1 <sha1>" in stderr replacing the original
assembly.
-``INTEL_BLACKHOLE_DEFAULT``
+:envvar:`INTEL_BLACKHOLE_DEFAULT`
if set to 1, true or yes, then the OpenGL implementation will
default ``GL_BLACKHOLE_RENDER_INTEL`` to true, thus disabling any
rendering.
@@ -358,7 +358,7 @@ i945/i965 driver environment variables (non-Gallium)
Radeon driver environment variables (radeon, r200, and r300g)
-------------------------------------------------------------
-``RADEON_NO_TCL``
+:envvar:`RADEON_NO_TCL`
if set, disable hardware-accelerated Transform/Clip/Lighting.
EGL environment variables
@@ -370,53 +370,53 @@ Mesa EGL supports different sets of environment variables. See the
Gallium environment variables
-----------------------------
-``GALLIUM_HUD``
+:envvar:`GALLIUM_HUD`
draws various information on the screen, like framerate, CPU load,
driver statistics, performance counters, etc. Set
- ``GALLIUM_HUD=help`` and run e.g. ``glxgears`` for more info.
-``GALLIUM_HUD_PERIOD``
+ :envvar:`GALLIUM_HUD` to ``help`` and run e.g. ``glxgears`` for more info.
+:envvar:`GALLIUM_HUD_PERIOD`
sets the HUD update rate in seconds (float). Use zero to update every
frame. The default period is 1/2 second.
-``GALLIUM_HUD_VISIBLE``
+:envvar:`GALLIUM_HUD_VISIBLE`
control default visibility, defaults to true.
-``GALLIUM_HUD_TOGGLE_SIGNAL``
+:envvar:`GALLIUM_HUD_TOGGLE_SIGNAL`
toggle visibility via user specified signal. Especially useful to
toggle HUD at specific points of application and disable for
unencumbered viewing the rest of the time. For example, set
- ``GALLIUM_HUD_VISIBLE`` to ``false`` and
- ``GALLIUM_HUD_TOGGLE_SIGNAL`` to ``10`` (``SIGUSR1``). Use
+ :envvar:`GALLIUM_HUD_VISIBLE` to ``false`` and
+ :envvar:`GALLIUM_HUD_TOGGLE_SIGNAL` to ``10`` (``SIGUSR1``). Use
``kill -10 <pid>`` to toggle the HUD as desired.
-``GALLIUM_HUD_SCALE``
+:envvar:`GALLIUM_HUD_SCALE`
Scale HUD by an integer factor, for high DPI displays. Default is 1.
-``GALLIUM_HUD_DUMP_DIR``
+:envvar:`GALLIUM_HUD_DUMP_DIR`
specifies a directory for writing the displayed HUD values into
files.
-``GALLIUM_DRIVER``
- useful in combination with ``LIBGL_ALWAYS_SOFTWARE=true`` for
+:envvar:`GALLIUM_DRIVER`
+ useful in combination with :envvar:`LIBGL_ALWAYS_SOFTWARE`=`true` for
choosing one of the software renderers ``softpipe``, ``llvmpipe`` or
``swr``.
-``GALLIUM_LOG_FILE``
+:envvar:`GALLIUM_LOG_FILE`
specifies a file for logging all errors, warnings, etc. rather than
stderr.
-``GALLIUM_PIPE_SEARCH_DIR``
+:envvar:`GALLIUM_PIPE_SEARCH_DIR`
specifies an alternate search directory for pipe-loader which overrides
the compile-time path based on the install location.
-``GALLIUM_PRINT_OPTIONS``
+:envvar:`GALLIUM_PRINT_OPTIONS`
if non-zero, print all the Gallium environment variables which are
used, and their current values.
-``GALLIUM_DUMP_CPU``
+:envvar:`GALLIUM_DUMP_CPU`
if non-zero, print information about the CPU on start-up
-``TGSI_PRINT_SANITY``
+:envvar:`TGSI_PRINT_SANITY`
if set, do extra sanity checking on TGSI shaders and print any errors
to stderr.
-``DRAW_FSE``
+:envvar:`DRAW_FSE`
???
-``DRAW_NO_FSE``
+:envvar:`DRAW_NO_FSE`
???
-``DRAW_USE_LLVM``
+:envvar:`DRAW_USE_LLVM`
if set to zero, the draw module will not use LLVM to execute shaders,
vertex fetch, etc.
-``ST_DEBUG``
+:envvar:`ST_DEBUG`
controls debug output from the Mesa/Gallium state tracker. Setting to
``tgsi``, for example, will print all the TGSI shaders. See
:file:`src/mesa/state_tracker/st_debug.c` for other options.
@@ -424,15 +424,15 @@ Gallium environment variables
Clover environment variables
----------------------------
-``CLOVER_EXTRA_BUILD_OPTIONS``
+:envvar:`CLOVER_EXTRA_BUILD_OPTIONS`
allows specifying additional compiler and linker options. Specified
options are appended after the options set by the OpenCL program in
``clBuildProgram``.
-``CLOVER_EXTRA_COMPILE_OPTIONS``
+:envvar:`CLOVER_EXTRA_COMPILE_OPTIONS`
allows specifying additional compiler options. Specified options are
appended after the options set by the OpenCL program in
``clCompileProgram``.
-``CLOVER_EXTRA_LINK_OPTIONS``
+:envvar:`CLOVER_EXTRA_LINK_OPTIONS`
allows specifying additional linker options. Specified options are
appended after the options set by the OpenCL program in
``clLinkProgram``.
@@ -440,7 +440,7 @@ Clover environment variables
Softpipe driver environment variables
-------------------------------------
-``SOFTPIPE_DEBUG``
+:envvar:`SOFTPIPE_DEBUG`
a comma-separated list of named flags, which do various things:
``vs``
@@ -463,15 +463,15 @@ Softpipe driver environment variables
LLVMpipe driver environment variables
-------------------------------------
-``LP_NO_RAST``
+:envvar:`LP_NO_RAST`
if set LLVMpipe will no-op rasterization
-``LP_DEBUG``
+:envvar:`LP_DEBUG`
a comma-separated list of debug options is accepted. See the source
code for details.
-``LP_PERF``
+:envvar:`LP_PERF`
a comma-separated list of options to selectively no-op various parts
of the driver. See the source code for details.
-``LP_NUM_THREADS``
+:envvar:`LP_NUM_THREADS`
an integer indicating how many threads to use for rendering. Zero
turns off threading completely. The default value is the number of
CPU cores present.
@@ -479,17 +479,17 @@ LLVMpipe driver environment variables
VMware SVGA driver environment variables
----------------------------------------
-``SVGA_FORCE_SWTNL``
+:envvar`SVGA_FORCE_SWTNL`
force use of software vertex transformation
-``SVGA_NO_SWTNL``
+:envvar`SVGA_NO_SWTNL`
don't allow software vertex transformation fallbacks (will often
result in incorrect rendering).
-``SVGA_DEBUG``
+:envvar`SVGA_DEBUG`
for dumping shaders, constant buffers, etc. See the code for details.
-``SVGA_EXTRA_LOGGING``
+:envvar`SVGA_EXTRA_LOGGING`
if set, enables extra logging to the ``vmware.log`` file, such as the
OpenGL program's name and command line arguments.
-``SVGA_NO_LOGGING``
+:envvar`SVGA_NO_LOGGING`
if set, disables logging to the ``vmware.log`` file. This is useful
when using Valgrind because it otherwise crashes when initializing
the host log feature.
@@ -499,7 +499,7 @@ See the driver code for other, lesser-used variables.
WGL environment variables
-------------------------
-``WGL_SWAP_INTERVAL``
+:envvar:`WGL_SWAP_INTERVAL`
to set a swap interval, equivalent to calling
``wglSwapIntervalEXT()`` in an application. If this environment
variable is set, application calls to ``wglSwapIntervalEXT()`` will
@@ -508,13 +508,13 @@ WGL environment variables
VA-API environment variables
----------------------------
-``VAAPI_MPEG4_ENABLED``
+:envvar:`VAAPI_MPEG4_ENABLED`
enable MPEG4 for VA-API, disabled by default.
VC4 driver environment variables
--------------------------------
-``VC4_DEBUG``
+:envvar:`VC4_DEBUG`
a comma-separated list of named flags, which do various things:
``cl``
@@ -543,7 +543,7 @@ VC4 driver environment variables
RADV driver environment variables
---------------------------------
-``RADV_DEBUG``
+:envvar:`RADV_DEBUG`
a comma-separated list of named flags, which do various things:
``llvm``
@@ -596,7 +596,8 @@ RADV driver environment variables
``notccompatcmask``
disable TC-compat CMASK for MSAA surfaces
``noumr``
- disable UMR dumps during GPU hang detection (only with RADV_DEBUG=hang)
+ disable UMR dumps during GPU hang detection (only with
+ :envvar:`RADV_DEBUG`=``hang``)
``novrsflatshading``
disable VRS for flat shading (only on GFX10.3+)
``preoptir``
@@ -616,15 +617,15 @@ RADV driver environment variables
``zerovram``
initialize all memory allocated in VRAM as zero
-``RADV_FORCE_FAMILY``
+:envvar:`RADV_FORCE_FAMILY`
create a null device to compile shaders without a AMD GPU (e.g. vega10)
-``RADV_FORCE_VRS``
+:envvar:`RADV_FORCE_VRS`
allow to force per-pipeline vertex VRS rates on GFX10.3+. This is only
forced for pipelines that don't explicitely use VRS or flat shading.
The supported values are 2x2, 1x2 and 2x1. Only for testing purposes.
-``RADV_PERFTEST``
+:envvar:`RADV_PERFTEST`
a comma-separated list of named flags, which do various things:
``bolist``
@@ -644,9 +645,10 @@ RADV driver environment variables
``sam``
enable optimizations to move more driver internal objects to VRAM.
-``RADV_TEX_ANISO``
+:envvar`RADV_TEX_ANISO`
force anisotropy filter (up to 16)
-``ACO_DEBUG``
+
+:envvar:`ACO_DEBUG`
a comma-separated list of named flags, which do various things:
``validateir``
@@ -672,7 +674,7 @@ RADV driver environment variables
radeonsi driver environment variables
-------------------------------------
-``AMD_DEBUG``
+:envvar:`AMD_DEBUG`
a comma-separated list of named flags, which do various things:
``nodcc``
@@ -775,7 +777,7 @@ radeonsi driver environment variables
r600 driver environment variables
---------------------------------
-``R600_DEBUG``
+:envvar:`R600_DEBUG`
a comma-separated list of named flags, which do various things:
``nocpdma``
@@ -865,15 +867,15 @@ r600 driver environment variables
``unsafemath``
Enable unsafe math shader optimizations
-``R600_DEBUG_COMPUTE``
+:envvar:`R600_DEBUG_COMPUTE`
if set to ``true``, various compute-related debug information will
be printed to stderr. Defaults to ``false``.
-``R600_DUMP_SHADERS``
+:envvar:`R600_DUMP_SHADERS`
if set to ``true``, NIR shaders will be printed to stderr. Defaults
to ``false``.
-``R600_HYPERZ``
+:envvar:`R600_HYPERZ`
If set to ``false``, disables HyperZ optimizations. Defaults to ``true``.
-``R600_NIR_DEBUG``
+:envvar:`R600_NIR_DEBUG`
a comma-separated list of named flags, which do various things:
``instr``
More information about the mesa-commit
mailing list