4 Normally, no environment variables need to be set. Most of the
5 environment variables used by Mesa/Gallium are for debugging purposes,
6 but they can sometimes be useful for debugging end-user issues.
8 LibGL environment variables
9 ---------------------------
12 If defined debug information will be printed to stderr. If set to
13 ``verbose`` additional information will be printed.
14 ``LIBGL_DRIVERS_PATH``
15 colon-separated list of paths to search for DRI drivers
16 ``LIBGL_ALWAYS_INDIRECT``
17 if set to ``true``, forces an indirect rendering context/connection.
18 ``LIBGL_ALWAYS_SOFTWARE``
19 if set to ``true``, always use software rendering
20 ``LIBGL_NO_DRAWARRAYS``
21 if set to ``true``, do not use DrawArrays GLX protocol (for
24 print framerate to stdout based on the number of ``glXSwapBuffers``
26 ``LIBGL_DRI3_DISABLE``
27 disable DRI3 if set to ``true``.
29 Core Mesa environment variables
30 -------------------------------
33 if set, disables all assembly language optimizations
35 if set, disables Intel MMX optimizations
37 if set, disables AMD 3DNow! optimizations
39 if set, disables Intel SSE optimizations
41 if set to 1, error checking is disabled as per ``KHR_no_error``. This
42 will result in undefined behaviour for invalid use of the api, but
43 can reduce CPU use for apps that are known to be error free.
45 if set, error messages are printed to stderr. For example, if the
46 application generates a ``GL_INVALID_ENUM`` error, a corresponding
47 error message indicating where the error occurred, and possibly why,
48 will be printed to stderr. For release builds, ``MESA_DEBUG``
49 defaults to off (no debug output). ``MESA_DEBUG`` accepts the
50 following comma-separated list of named flags, which adds extra
51 behaviour to just set ``MESA_DEBUG=1``:
54 turn off debug messages. Only useful for debug builds.
56 flush after each drawing command
58 extra debug messages when a texture is incomplete
60 extra debug messages when a fbo is incomplete
62 create a debug context (see ``GLX_CONTEXT_DEBUG_BIT_ARB``) and
63 print error and performance messages to stderr (or
67 specifies a file name for logging all errors, warnings, etc., rather
70 if set, implement conventional texture env modes with fragment
71 programs (intended for developers only)
73 if set, implement conventional vertex transformation operations with
74 vertex programs (intended for developers only). Setting this variable
75 automatically sets the ``MESA_TEX_PROG`` variable as well.
76 ``MESA_EXTENSION_OVERRIDE``
77 can be used to enable/disable extensions. A value such as
78 ``GL_EXT_foo -GL_EXT_bar`` will enable the ``GL_EXT_foo`` extension
79 and disable the ``GL_EXT_bar`` extension.
80 ``MESA_EXTENSION_MAX_YEAR``
81 The ``GL_EXTENSIONS`` string returned by Mesa is sorted by extension
82 year. If this variable is set to year X, only extensions defined on
83 or before year X will be reported. This is to work-around a bug in
84 some games where the extension string is copied into a fixed-size
85 buffer without truncating. If the extension string is too long, the
86 buffer overrun can cause the game to crash. This is a work-around for
88 ``MESA_GL_VERSION_OVERRIDE``
89 changes the value returned by ``glGetString(GL_VERSION)`` and
90 possibly the GL API type.
92 - The format should be ``MAJOR.MINOR[FC|COMPAT]``
93 - ``FC`` is an optional suffix that indicates a forward compatible
94 context. This is only valid for versions >= 3.0.
95 - ``COMPAT`` is an optional suffix that indicates a compatibility
96 context or ``GL_ARB_compatibility`` support. This is only valid
98 - GL versions <= 3.0 are set to a compatibility (non-Core) profile
99 - GL versions = 3.1, depending on the driver, it may or may not have
100 the ``ARB_compatibility`` extension enabled.
101 - GL versions >= 3.2 are set to a Core profile
105 select a compatibility (non-Core) profile with GL version 2.1.
107 select a compatibility (non-Core) profile with GL version 3.0.
109 select a Core+Forward Compatible profile with GL version 3.0.
111 select GL version 3.1 with ``GL_ARB_compatibility`` enabled per
114 select GL version 3.1 with forward compatibility and
115 ``GL_ARB_compatibility`` disabled.
117 select GL version 3.1 with ``GL_ARB_compatibility`` enabled.
119 override GL version to X.Y without changing the profile.
121 select a Core+Forward Compatible profile with GL version X.Y.
123 select a Compatibility profile with GL version X.Y.
125 - Mesa may not really implement all the features of the given
126 version. (for developers only)
128 ``MESA_GLES_VERSION_OVERRIDE``
129 changes the value returned by ``glGetString(GL_VERSION)`` for OpenGL
132 - The format should be ``MAJOR.MINOR``
133 - Examples: ``2.0``, ``3.0``, ``3.1``
134 - Mesa may not really implement all the features of the given
135 version. (for developers only)
137 ``MESA_GLSL_VERSION_OVERRIDE``
138 changes the value returned by
139 ``glGetString(GL_SHADING_LANGUAGE_VERSION)``. Valid values are
140 integers, such as ``130``. Mesa will not really implement all the
141 features of the given language version if it's higher than what's
142 normally reported. (for developers only)
143 ``MESA_GLSL_CACHE_DISABLE``
144 if set to ``true``, disables the GLSL shader cache
145 ``MESA_GLSL_CACHE_MAX_SIZE``
146 if set, determines the maximum size of the on-disk cache of compiled
147 GLSL programs. Should be set to a number optionally followed by
148 ``K``, ``M``, or ``G`` to specify a size in kilobytes, megabytes, or
149 gigabytes. By default, gigabytes will be assumed. And if unset, a
150 maximum size of 1GB will be used. Note: A separate cache might be
151 created for each architecture that Mesa is installed for on your
152 system. For example under the default settings you may end up with a
153 1GB cache for x86_64 and another 1GB cache for i386.
154 ``MESA_GLSL_CACHE_DIR``
155 if set, determines the directory to be used for the on-disk cache of
156 compiled GLSL programs. If this variable is not set, then the cache
157 will be stored in ``$XDG_CACHE_HOME/mesa_shader_cache`` (if that
158 variable is set), or else within ``.cache/mesa_shader_cache`` within
159 the user's home directory.
161 `shading language compiler options <shading.html#envvars>`__
162 ``MESA_NO_MINMAX_CACHE``
163 when set, the minmax index cache is globally disabled.
164 ``MESA_SHADER_CAPTURE_PATH``
165 see `Capturing Shaders <shading.html#capture>`__
166 ``MESA_SHADER_DUMP_PATH`` and ``MESA_SHADER_READ_PATH``
167 see `Experimenting with Shader
168 Replacements <shading.html#replacement>`__
169 ``MESA_VK_VERSION_OVERRIDE``
170 changes the Vulkan physical device version as returned in
171 ``VkPhysicalDeviceProperties::apiVersion``.
173 - The format should be ``MAJOR.MINOR[.PATCH]``
174 - This will not let you force a version higher than the driver's
175 instance version as advertised by ``vkEnumerateInstanceVersion``
176 - This can be very useful for debugging but some features may not be
177 implemented correctly. (For developers only)
179 NIR passes enviroment variables
180 -------------------------------
182 The following are only applicable for drivers that uses NIR, as they
183 modify the behaviour for the common NIR_PASS and NIR_PASS_V macros, that
184 wrap calls to NIR lowering/optimizations.
187 If defined, the resulting NIR shader will be printed out at each
188 succesful NIR lowering/optimization call.
190 If defined, cloning a NIR shader would be tested at each succesful
191 NIR lowering/optimization call.
192 ``NIR_TEST_SERIALIZE``
193 If defined, serialize and deserialize a NIR shader would be tested at
194 each succesful NIR lowering/optimization call.
196 Mesa Xlib driver environment variables
197 --------------------------------------
199 The following are only applicable to the Mesa Xlib software driver. See
200 the `Xlib software driver page <xlibdriver.html>`__ for details.
203 specifies the X visual and depth for RGB mode
205 specifies the X visual and depth for CI mode
207 specifies how to implement the back color buffer, either ``pixmap``
210 gamma correction coefficients for red, green, blue channels
212 enable synchronous X behavior (for debugging only)
213 ``MESA_GLX_FORCE_CI``
214 if set, force GLX to treat 8bpp visuals as CI visuals
215 ``MESA_GLX_FORCE_ALPHA``
216 if set, forces RGB windows to have an alpha channel.
217 ``MESA_GLX_DEPTH_BITS``
218 specifies default number of bits for depth buffer.
219 ``MESA_GLX_ALPHA_BITS``
220 specifies default number of bits for alpha channel.
222 i945/i965 driver environment variables (non-Gallium)
223 ----------------------------------------------------
226 if set to 1, prevents batches from being submitted to the hardware.
227 This is useful for debugging hangs, etc.
229 a comma-separated list of named flags, which do various things:
232 annotate IR in assembly dumps
234 dump batches into an AUB trace for use with simulation tools
236 emit batch information
238 emit messages about blit operations
240 emit messages about the blorp operations (blits & clears)
242 emit messages about buffer objects
244 emit messages about the clip unit (for old gens, includes the CLIP
249 dump shader assembly for compute shaders
251 generate compute shader SIMD32 programs even if workgroup size
252 doesn't exceed the SIMD16 limit
254 emit messages about the DRI interface
256 emit messages about framebuffers
258 dump shader assembly for fragment shaders
260 dump shader assembly for geometry shaders
262 print instruction hex dump with the disassembly
264 emit messages about the new L3 state during transitions
266 emit messages about miptrees
268 don't generate SIMD8 fragment shader
270 suppress generation of 16-wide fragment shaders. useful for
271 debugging broken shaders
273 disable instruction compaction
275 suppress generation of dual-object geometry shader code
279 disable single sampled render buffer compression
281 dump shader assembly to files at each optimization pass and
282 iteration that make progress
284 emit messages about performance issues
286 emit messages about ``AMD_performance_monitor``
288 emit messages about pixel operations
290 emit messages about drawing primitives
292 mark all state dirty on each draw call
294 emit messages about the strips & fans unit (for old gens, includes
297 record how much GPU time is spent in each shader
299 force spilling of all registers in the scalar backend (useful to
302 force spilling of all registers in the vec4 backend (useful to
305 emit messages about state flag tracking
307 emit batchbuffer usage statistics
309 after sending each batch, emit a message and wait for that batch
312 dump shader assembly for tessellation control shaders
314 dump shader assembly for tessellation evaluation shaders
316 emit messages about textures.
318 emit messages about URB setup
320 emit messages about vertex assembly
322 dump shader assembly for vertex shaders
324 ``INTEL_SCALAR_VS`` (or ``TCS``, ``TES``, ``GS``)
325 force scalar/vec4 mode for a shader stage (Gen8-9 only)
326 ``INTEL_PRECISE_TRIG``
327 if set to 1, true or yes, then the driver prefers accuracy over
328 performance in trig functions.
330 Radeon driver environment variables (radeon, r200, and r300g)
331 -------------------------------------------------------------
334 if set, disable hardware-accelerated Transform/Clip/Lighting.
336 EGL environment variables
337 -------------------------
339 Mesa EGL supports different sets of environment variables. See the `Mesa
340 EGL <egl.html>`__ page for the details.
342 Gallium environment variables
343 -----------------------------
346 draws various information on the screen, like framerate, cpu load,
347 driver statistics, performance counters, etc. Set
348 ``GALLIUM_HUD=help`` and run e.g. ``glxgears`` for more info.
349 ``GALLIUM_HUD_PERIOD``
350 sets the hud update rate in seconds (float). Use zero to update every
351 frame. The default period is 1/2 second.
352 ``GALLIUM_HUD_VISIBLE``
353 control default visibility, defaults to true.
354 ``GALLIUM_HUD_TOGGLE_SIGNAL``
355 toggle visibility via user specified signal. Especially useful to
356 toggle hud at specific points of application and disable for
357 unencumbered viewing the rest of the time. For example, set
358 ``GALLIUM_HUD_VISIBLE`` to ``false`` and
359 ``GALLIUM_HUD_TOGGLE_SIGNAL`` to ``10`` (``SIGUSR1``). Use
360 ``kill -10 <pid>`` to toggle the hud as desired.
361 ``GALLIUM_HUD_SCALE``
362 Scale hud by an integer factor, for high DPI displays. Default is 1.
363 ``GALLIUM_HUD_DUMP_DIR``
364 specifies a directory for writing the displayed hud values into
367 useful in combination with ``LIBGL_ALWAYS_SOFTWARE=true`` for
368 choosing one of the software renderers ``softpipe``, ``llvmpipe`` or
371 specifies a file for logging all errors, warnings, etc. rather than
373 ``GALLIUM_PRINT_OPTIONS``
374 if non-zero, print all the Gallium environment variables which are
375 used, and their current values.
377 if non-zero, print information about the CPU on start-up
378 ``TGSI_PRINT_SANITY``
379 if set, do extra sanity checking on TGSI shaders and print any errors
386 if set to zero, the draw module will not use LLVM to execute shaders,
389 controls debug output from the Mesa/Gallium state tracker. Setting to
390 ``tgsi``, for example, will print all the TGSI shaders. See
391 ``src/mesa/state_tracker/st_debug.c`` for other options.
393 Clover environment variables
394 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
396 ``CLOVER_EXTRA_BUILD_OPTIONS``
397 allows specifying additional compiler and linker options. Specified
398 options are appended after the options set by the OpenCL program in
400 ``CLOVER_EXTRA_COMPILE_OPTIONS``
401 allows specifying additional compiler options. Specified options are
402 appended after the options set by the OpenCL program in
403 ``clCompileProgram``.
404 ``CLOVER_EXTRA_LINK_OPTIONS``
405 allows specifying additional linker options. Specified options are
406 appended after the options set by the OpenCL program in
409 Softpipe driver environment variables
410 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
413 if set, the softpipe driver will print fragment shaders to stderr
415 if set, the softpipe driver will print geometry shaders to stderr
417 if set, rasterization is no-op'd. For profiling purposes.
418 ``SOFTPIPE_USE_LLVM``
419 if set, the softpipe driver will try to use LLVM JIT for vertex
422 LLVMpipe driver environment variables
423 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
426 if set LLVMpipe will no-op rasterization
428 a comma-separated list of debug options is accepted. See the source
431 a comma-separated list of options to selectively no-op various parts
432 of the driver. See the source code for details.
434 an integer indicating how many threads to use for rendering. Zero
435 turns off threading completely. The default value is the number of
438 VMware SVGA driver environment variables
439 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
442 force use of software vertex transformation
444 don't allow software vertex transformation fallbacks (will often
445 result in incorrect rendering).
447 for dumping shaders, constant buffers, etc. See the code for details.
448 ``SVGA_EXTRA_LOGGING``
449 if set, enables extra logging to the ``vmware.log`` file, such as the
450 OpenGL program's name and command line arguments.
452 if set, disables logging to the ``vmware.log`` file. This is useful
453 when using Valgrind because it otherwise crashes when initializing
454 the host log feature.
456 See the driver code for other, lesser-used variables.
458 WGL environment variables
459 ~~~~~~~~~~~~~~~~~~~~~~~~~
461 ``WGL_SWAP_INTERVAL``
462 to set a swap interval, equivalent to calling
463 ``wglSwapIntervalEXT()`` in an application. If this environment
464 variable is set, application calls to ``wglSwapIntervalEXT()`` will
467 VA-API environment variables
468 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
470 ``VAAPI_MPEG4_ENABLED``
471 enable MPEG4 for VA-API, disabled by default.
473 VC4 driver environment variables
474 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
477 a comma-separated list of named flags, which do various things:
480 dump command list during creation
482 dump generated QPU instructions
484 dump QPU IR during program compile
486 dump NIR during program compile
488 dump TGSI during program compile
490 dump program compile information for shader-db analysis
492 print during performance-related events
494 skip actual hardware execution of commands
496 flush after each draw call
498 wait for finish after each flush
500 write a GPU command stream trace file (VC4 simulator only)
502 RADV driver environment variables
503 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
506 a comma-separated list of named flags, which do various things:
509 force all allocated buffers to be referenced in submissions
511 enable all device/instance entrypoints
513 validate the LLVM IR before LLVM compiles the shader
515 display more info about errors
517 show GPU-related information
519 dump internal meta shaders
521 disable primitive binning
523 disable shaders cache
525 disable compute queue
527 disable Delta Color Compression (DCC) on images
529 do not check OOB access for dynamic descriptors
531 disable fast color/depthstencil clears
533 disable HIZ for depthstencil images
535 disable directly recording command buffers in GPU-visible memory
537 disable LLVM SILoadStoreOptimizer pass
539 disable memory shaders cache
541 disable NGG for GFX10+
543 disable out-of-order rasterization
545 disable shader ballot
547 disable LLVM threaded compilation
549 dump LLVM IR before any optimizations
553 dump shader statistics
557 display info at startup
559 synchronize shaders after all draws/dispatches
561 check for VM memory faults via dmesg
563 initialize all memory allocated in VRAM as zero
565 ``RADV_FORCE_FAMILY``
566 create a null device to compile shaders without a AMD GPU (eg.
569 a comma-separated list of named flags, which do various things:
572 enable ACO experimental compiler
574 enable the global BO list
576 enable wave32 for compute shaders (GFX10+)
578 enable DCC for MSAA images
582 enable wave32 for vertex/tess/geometry shaders (GFX10+)
586 enable wave32 for pixel shaders (GFX10+)
590 enable TC-compat cmask for MSAA images
592 ``RADV_SECURE_COMPILE_THREADS``
593 maximum number of secure compile threads (up to 32)
595 force anisotropy filter (up to 16)
597 generate cmdbuffer tracefiles when a GPU hang is detected
599 a comma-separated list of named flags, which do various things:
602 validate the ACO IR at various points of compilation (enabled by
603 default for debug/debugoptimized builds)
605 validate register assignment of ACO IR and catches many RA bugs
607 abort on some suboptimal code generation
609 radeonsi driver environment variables
610 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
613 a comma-separated list of named flags, which do various things:
619 Disable SDMA image copies
621 Clear VRAM allocations.
625 Disable DCC fast clear.
627 Disable separate DCC on the main framebuffer
637 Disable MSAA compression
645 Print driver information
651 Print virtual addresses when creating resources
657 Print geometry shaders
659 Print tessellation control shaders
661 Print tessellation evaluation shaders
663 Print compute shaders
665 Don't print the LLVM IR
667 Don't print NIR when printing shaders
669 Don't print disassembled shaders
671 Print the LLVM IR before initial optimizations
673 Enable LLVM global instruction selector.
675 Use Wave32 for vertex, tessellation, and geometry shaders.
677 Use Wave32 for pixel shaders.
679 Use Wave32 for computes shaders.
681 Use Wave64 for vertex, tessellation, and geometry shaders.
683 Use Wave64 for pixel shaders.
685 Use Wave64 for computes shaders.
687 Enable additional sanity checks on shader IR
689 Use old-style monolithic shaders compiled on demand
691 Disable compiling optimized shader variants.
693 Use SDMA for all operations when possible.
695 Disable GTT write combining
697 Check VM faults and dump debug info.
699 Force VMID reservation per context.
701 Disable graphics. Only multimedia compute paths can be used.
703 Disable NGG and use the legacy pipeline.
705 Always use NGG culling even when it can hurt.
709 Always enable the primitive discard compute shader.
711 Enable the primitive discard compute shader for large draw calls.
713 Disable the primitive discard compute shader.
715 Program WD/IA to switch on end-of-packet.
717 Disable out-of-order rasterization
723 Other Gallium drivers have their own environment variables. These may
724 change frequently so the source code should be consulted for details.