search

pal1000 / mesa-dist-win

Pre-built Mesa3D drivers for Windows
MIT License
860 stars 77 forks source link
buggy driver gpu mesa3d-drivers mingw-w64 msvc windows workaround

readme

Table of Contents

Screenshot 2023-10-25 201821 Screenshot_20221205_065713

Known issues

This is a list of all comonly encountered issues with known solutions or workarounds. A specific release is only affected by a subset of them.

This is encountered with existing per application deployments made with 21.2.x or older when updating to 21.3.0 or newer. Just redo per app deployment to fix it. Gallium megadriver separation from opengl32.dll was a very invasive change that existing per app deployments didn't stand a chance against. 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 location ends in x64 then it's 64-bit, otherwise it's 32-bit.

This is encountered with existing per application deployments made with 21.2.x or older when updating to 21.3.0 or newer. Just redo per app deployment to fix it. The EGL support was a very invasive change that existing per app deployments didn't stand a chance against. 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 location ends in x64 then it's 64-bit, otherwise it's 32-bit.

Only releases prior to 22.2.0 for which zink driver was built with MSYS2 MinGW-W64 vulkan-devel package group are affected. Run fix-libvulkan-1.dll-missing-error.cmd from MinGW release package to correct it. This tool supports unattended execution via auto command line option. This tool is only bundled in MinGW release package when needed otherwise it's intentionally missing. The decision to use this Vulkan SDK over LunarG's is done based on which comes with newer loader and headers.

This is no longer an issue as of Mesa 22.0 or newer. This issue is caused by 64-bit binaries containing swr driver which leaks AVX usage into common code. This is an upstream bug reported here, here and here.

This is not a defect but rather a behavior change of Mesa when environment variables are misconfigured. It usually happens when selecting a Mesa driver that doesn't exist in release package used or it fails to initialize due to host system not meeting hardware requirements or lacking dependencies. Reading differences between MSVC and MinGW packages and Mingw and MSVC Package contents should aid in troubleshooting.

You may experience them with programs that use any Mesa3D desktop OpenGL driver via per app deployment tool, system wide deployment is unaffected. You may experience them if per app deployment was done before shared glapi support was introduced. shared glapi has been consistently available in both MSVC and MinGW packages since 20.0.2.

To correct these errors regardless of cause you have to re-deploy. 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 location ends in x64 then it's 64-bit, otherwise it's 32-bit.

Same problem with same solution applies to osmesa if you are upgrading from 17.3.5.501-1 or older.

Differences between MSVC and MinGW packages

If you need to migrate from Mingw to MSVC binaries you just need to replace Mesa binaries folder from Mingw package with MSVC counterpart.

Mingw and MSVC Package contents

The following Mesa3D drivers and build artifacts are shipped in each release:

OpenGL and OpenGL ES common shared libraries

Examples on OpenGL context configuration override, switch to other driver and old applications compatibility are available here.

WARNING: Programs for which certain files have been overwritten by per application deployment tool may need re-installation/repair. Per application deployment tool detects and warns about this deployment scenario since 22.0.0.

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.

Ex: 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 delay work in this area until Mesa 18.1 introduced GL_ARB_compatibility support and then Mesa 21.3 bumped compatibility contexts support to OpenGL 4.5 for llvmpipe. In conclusion programs requesting OpenGL compatibility context won't get above OpenGL 3.0 for Mesa 18.0, 3.1 for Mesa 18.1 and 4.5 for Mesa 21.3 and newer. 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

OpenGLMajorVersion.OpenGLMinorVersion{FC|COMPAT].

FC means a forward compatible context. COMPAT means a compatibility context for OpenGL 3.2 and newer and GL_ARB_compatibility being enabled 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 with GL_ARB_compatibility , 3.2 means OpenGL 3.2 core profile. The default value for llvmpipe driver is 4.5COMPAT for Mesa>=21.3, 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 llvmpipe is certified for OpenGL 4.5 in all OpenGL profiles. Currently swr and GLonD3D12 are certified for OpenGL 3.3 in core profile / forward compatible context and 3.1 in compatibility profile. zink OpenGL support depends on underlying Vulkan driver. 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 for llvmpipe: 450 for Mesa 21.3, 140 for Mesa 18.1 and 130 for Mesa 18.0 if MESA_GL_VERSION_OVERRIDE is undefined or matching core profile's 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:

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.