Table of Contents
- Note for enterprise environments
- About Mingw package
- Mingw and MSVC Package contents
- Installation and usage
- Legacy software compatibility
- OpenGL context configuration override
- How to set environment variables
Mesa 19.0.5 builds with Visual Studio and MSYS2 Mingw-w64 are now available in releases section.
Note for enterprise environments
IT security policy may restrict or even outright prohibit running 3rd-party unsigned executables. If this is the case you can extract Mesa3D drivers using 7-Zip.
About Mingw package
Mingw package is recommended in most cases over MSVC as it has better performance but it also has 2 caveats:
If you need to migrate from Mingw to MSVC binaries you have to make sure you replace
opengl32.dll from Mingw package with MSVC counterpart otherwise swr driver won't load even if you set
Mingw and MSVC Package contents
The following Mesa3D drivers and build artifacts are shipped in each release:
- llvmpipe and softpipe bundle. File name: opengl32.dll. llvmpipe is the default desktop OpenGL driver. Both llvmpipe and softpipe are available for both x86 and x64. softpipe can be selected by setting environment variable GALLIUM_DRIVER=softpipe.
- GLAPI shared library. It is no longer available for Scons build used on Windows since Mesa3D 18.3.0 due to problems with osmesa build in this configuration, see this commit. However it may be resurrected with Meson build, but unfortunately it is running late upstream. File name: libglapi.dll. Required by llvmpipe, softpipe and swr if Mesa3D is built with shared glapi. This was indeed the case since 188.8.131.520-1 up to and including 18.2.6, see #8.
- swr. File names: swrAVX.dll, swrAVX2.dll. An alternative desktop OpenGL driver developed by Intel. Available only in MSVC package and only for x64, x86 is officially unsupported. There are currently 2 DLLs, only one being loaded based on what the user CPU can do. 2 more will join soon matching the existing flavors of AVX512 instruction set, see issue #2. By default Mesa uses llvmpipe. You can switch to swr by setting GALLIUM_DRIVER environment variable value to swr either globally or in a batch file. See How to set environment variables.
- OpenGL ES standalone drivers. These drivers are no longer available since Mesa 18.3 due to support being suspended upstream for same reason as for shared glapi which they depend on. File names: libGLESv1_CM.dll and libGLESv2.dll. OpenGL ES 1.x, 2.0 and 3.0 standalone drivers available for 32-bit and 64-bit applications.
- osmesa. File name: osmesa.dll. 2 versions of osmesa, off-screen rendering driver. They are located in osmesa-gallium and osmesa-swrast subdirectories. Available for both x86 and x64. This driver is used in special cases by software that is designed to use Mesa code to render without any kind of window system or operating system dependency. osmesa gallium supports OpenGL 3.x and newer while osmesa swrast also known as osmesa classic only supports OpenGL 2.1 but it has some unique capabilities. osmesa has integration with standalone GLLES drivers stripped which may impact integration with softpipe, llvmpipe and swr due to build failure. osmesa and glapi linking bug report is filed here.
- graw. File name: graw.dll. This is Mesa3D plug-in library. It is not a driver. Available for both x86 and x64. This is used in special cases by software that is designed to use Mesa code. While Mesa includes a full version bearing the build target of graw-gdi and a headless version bearing the build target of graw-null, only the full version is included. The headless version can be easily added upon request in a later release.
- libraries and headers generated at build time for both 32-bit and 64-bit builds in a separate archive called development pack. Note that build time generated headers depend on source code headers, so you may need Mesa3D source code because only build time headers are included.
Build instructions, if you want to replicate my builds, are available here.
Installation and usage
First choose between Mingw and MSVC package. See About Mingw package section for details. Before running the installer close all programs that use Mesa if any is running. After running the installer you will have access to 2 deployment options, both located in the directory you installed Mesa. Both deployment utilities have a start-over mechanism so you can do all deployments you need in one session.
- A system-wide deployment tool. While intended for systems lacking hardware accelerated OpenGL support like virtual machines in cloud environments, it can also be used on any Windows system to replace the inbox software rendering OpenGL 1.1 driver extending OpenGL support for use cases where hardware accelerated OpenGL is not available like RDP connections. Due to potential issues with Virtualbox VMs running Windows it is recommended to disable 3D acceleration in such VMs if Mesa3D desktop OpenGL driver is installed inside them using the system-wide deployment tool, see #9.
- A per-application deployment tool. If you used it to deploy desktop OpenGL driver and you are upgrading from 184.108.40.2060-1 or older to 220.127.116.110-1 or newer you may have to re-deploy it to avoid an error related to
libglapi.dll. If you don't remember if an affected program is 32-bit or 64-bit, right click on opengl32.dll shortcut in the folder where the program executable is located and select open file location. If the location ends in x64 then it's 64-bit otherwise it's 32-bit. Same for osmesa if you are upgrading from 18.104.22.1681-1 or older. Per-app deployment utility changes are persistent and are being kept across upgrades and re-installations. The per-app deployment utility helps you save storage and makes things easier as you won't have to manually copy DLLs from Mesa installation directory as it creates symbolic links to whatever Mesa drivers you opt-in to use. This behavior ensures all programs that use Mesa use the same up-to-date version. Per-app deployment utility only asks for path to directory containing application executable, application executable filename (optional, it can remain blank), if the app is 64-bit or 32-bit and the drivers you need. 32-bit applications have their names marked in Task Manager while running. Most applications will use Mesa regardless of GPU capabilities, but some applications may be smart enough to load OpenGL from system directory only. By providing the application filename, a .local file is generated in an attempt to force the application to use Mesa3D when it doesn't want to. Also, Federico Dossena's Mesainjector can be used to workaround this issue. Build instructions for Mesainjector.
Since v22.214.171.1241 in-place upgrade is fully supported. Since v126.96.36.1991-2 S3 texture compression is supported. v188.8.131.521-1 requires uninstall of previous versions. Old applications from early 200x and older may need MESA_EXTENSION_MAX_YEAR environment variable set, see legacy software compatibility section. Applications requiring OpenGL 3.2 or newer may need OpenGL context configuration override.
Legacy software compatibility
Old applications from early 200x and older may need MESA_EXTENSION_MAX_YEAR environment variable set to avoid buffer overflows. It expects a year number as value, most commonly used being 2001. It trims the extensions list returned by Mesa3D to extensions released up to and including provided year as Mesa3D extensions list is sorted by year.
set MESA_EXTENSION_MAX_YEAR=2001. See How to set environment variables.
OpenGL context configuration override
With release of OpenGL 3.1 many features marked as deprecated in OpenGL 3.0 have been removed and since OpenGL 3.2 launch this OpenGL specification branch is known as OpenGL Core profile. Also in OpenGL 3.3 a new branch of the OpenGL specification known as forward compatible context was introduced which removes the OpenGL 3.0 deprecated features that were not removed in OpenGL 3.1. Most proprietary drivers implemented the exemptions from these changes offered in the form of GL_ARB_compatibility extension for OpenGL 3.1 and compatibility contexts for OpenGL 3.2 and above. Due to complexity and especially lack of correct implementation tests for GL_ARB_compatibility and compatibility contexts, Mesa3D developers chose to retain features deprecated in OpenGL 3.0 and implement Core profile and forward compatible contexts. Mesa 18.1 introduced GL_ARB_compatibility support making the first step toward having compatibility contexts support in the future. Because GL_ARB_compatibility is only for OpenGL 3.1, programs requesting OpenGL compatibility context won't get above OpenGL 3.0 for Mesa 18.0 and 3.1 for Mesa 18.1. Unfortunately these kind of programs are prevalent on Windows where developers tend to avoid using context flags required by Core profile. Fortunately Mesa3D provides a mechanism to override the OpenGL context requested. There are 2 environment variables that override OpenGL context configuration:
It is used to specify OpenGL context version and type. It expects a value in the following format
FC means a forward compatible context. COMPAT means a compatibility context for OpenGL 3.2 and newer and GL_ARB_compatibility being available for OpenGL 3.1. Absence of any string after version number means the Mesa3D default context type for OpenGL version specified which is as follows: deprecated features enabled for OpenGL 3.0, GL_ARB_compatibility enabled for OpenGL 3.1 since Mesa 18.1 and Core profile for OpenGL 3.2 and above. Examples: 3.3FC means OpenGL 3.3 forward compatible context, 3.1COMPAT means OpenGL 3.1 compatibility context or to be more accurate OpenGL 3.1 with GL_ARB_compatibility , 3.2 means OpenGL 3.2 core profile. The default value is 3.1COMPAT for Mesa 18.1 and 3.0COMPAT for Mesa 18.0.
A very important feature provided by this variable is the possibility to configure an incomplete OpenGL context. Programs can only request up to the highest OpenGL context with Khronos certification as complete from Mesa3D driver in use. Currently both llvmpipe and swr are certified for OpenGL 3.3, yet the rpcs3 context configuration sample uses OpenGL 4.3 and it works. This is because despite the context not being complete, the required extensions by rpcs3 are in place. Since Mesa 17.3 values meant for OpenGL 4.6 are recognized.
Used to specify shading language version. Supported values are version numbers converted to integer: 110, 120, 130, 140. 150, 330, 400, 410, 420, 430, 440, 450 and 460. Value 460 is only recognized since Mesa 17.3. Value 130 for example matches GLSL 1.30. It is always a good idea to keep OpenGL context and shading language versions in sync to avoid programs confusion which may result in crashes or glitches. This can happen because most applications rely on proprietary drivers behavior of having OpenGL and GLSL versions in sync. Here is the OpenGL - GLSL correlation table. Default values: 140 for Mesa 18.1 and 130 for Mesa 18.0 if MESA_GL_VERSION_OVERRIDE is undefined or 330 otherwise.
How to set environment variables
Under Windows the easiest way to set environment variables is by writing batch files. You'll most likely need to do so:
- for every application requiring OpenGL 3.2 or newer in compatibility profile or 4.0 or newer in core profile;
- if your want to use swr instead of llvmpipe for desktop OpenGL;
- if you need to trim extensions list for old programs compatibility.
Simply open Notepad, write the batch script. When saving, end the file name with .bat or .cmd, change save as type to all files and change save location to where the application executable is located. If you have some skill with batch scripts you can change the current directory during script execution using CD command opening the possibility to save the script anywhere you want as shown in rpcs3 and GPU Caps Viewer examples. Documentation of most environment variables used by Mesa is available here. Complete examples are available here.
You can set multiple environment variables on same batch script to mix the functionality provided by Mesa3D.