Expand description of Mesa3D drivers available on Windows - #55 and #59

Release 21.0.2

buildinfo/mingw.txt

@@ -83,21 +83,21 @@ m4 1.4.18-2
 mingw-w64-i686-binutils 2.36.1-3
 mingw-w64-i686-bzip2 1.0.8-2
 mingw-w64-i686-ca-certificates 20200601-3
-mingw-w64-i686-crt-git 9.0.0.6144.45def5d7-1
+mingw-w64-i686-crt-git 9.0.0.6154.e37b315b-1
 mingw-w64-i686-expat 2.2.10-1
 mingw-w64-i686-gcc 10.2.0-9
 mingw-w64-i686-gcc-libs 10.2.0-9
 mingw-w64-i686-gdb 10.1-2
 mingw-w64-i686-gettext 0.19.8.1-10
 mingw-w64-i686-gmp 6.2.1-1
-mingw-w64-i686-headers-git 9.0.0.6144.45def5d7-2
+mingw-w64-i686-headers-git 9.0.0.6154.e37b315b-1
 mingw-w64-i686-isl 0.23-1
 mingw-w64-i686-libffi 3.3-3
 mingw-w64-i686-libiconv 1.16-2
 mingw-w64-i686-libsystre 1.0.1-4
 mingw-w64-i686-libtasn1 4.16.0-1
 mingw-w64-i686-libtre-git r128.6fb7206-2
-mingw-w64-i686-libwinpthread-git 9.0.0.6144.45def5d7-1
+mingw-w64-i686-libwinpthread-git 9.0.0.6154.e37b315b-1
 mingw-w64-i686-llvm 11.0.0-8
 mingw-w64-i686-meson 0.57.1-2
 mingw-w64-i686-mpc 1.2.1-1
@@ -123,7 +123,7 @@ mingw-w64-i686-vulkan-headers 1.2.168-2
 mingw-w64-i686-vulkan-loader 1.2.166-1
 mingw-w64-i686-vulkan-validation-layers 1.2.162-3
 mingw-w64-i686-windows-default-manifest 6.4-3
-mingw-w64-i686-winpthreads-git 9.0.0.6144.45def5d7-1
+mingw-w64-i686-winpthreads-git 9.0.0.6154.e37b315b-1
 mingw-w64-i686-xxhash 0.8.0-1
 mingw-w64-i686-xz 5.2.5-2
 mingw-w64-i686-z3 4.8.9-1
@@ -132,21 +132,21 @@ mingw-w64-i686-zstd 1.4.8-2
 mingw-w64-x86_64-binutils 2.36.1-3
 mingw-w64-x86_64-bzip2 1.0.8-2
 mingw-w64-x86_64-ca-certificates 20200601-3
-mingw-w64-x86_64-crt-git 9.0.0.6144.45def5d7-1
+mingw-w64-x86_64-crt-git 9.0.0.6154.e37b315b-1
 mingw-w64-x86_64-expat 2.2.10-1
 mingw-w64-x86_64-gcc 10.2.0-9
 mingw-w64-x86_64-gcc-libs 10.2.0-9
 mingw-w64-x86_64-gdb 10.1-2
 mingw-w64-x86_64-gettext 0.19.8.1-10
 mingw-w64-x86_64-gmp 6.2.1-1
-mingw-w64-x86_64-headers-git 9.0.0.6144.45def5d7-2
+mingw-w64-x86_64-headers-git 9.0.0.6154.e37b315b-1
 mingw-w64-x86_64-isl 0.23-1
 mingw-w64-x86_64-libffi 3.3-3
 mingw-w64-x86_64-libiconv 1.16-2
 mingw-w64-x86_64-libsystre 1.0.1-4
 mingw-w64-x86_64-libtasn1 4.16.0-1
 mingw-w64-x86_64-libtre-git r128.6fb7206-2
-mingw-w64-x86_64-libwinpthread-git 9.0.0.6144.45def5d7-1
+mingw-w64-x86_64-libwinpthread-git 9.0.0.6154.e37b315b-1
 mingw-w64-x86_64-llvm 11.0.0-8
 mingw-w64-x86_64-meson 0.57.1-2
 mingw-w64-x86_64-mpc 1.2.1-1
@@ -172,7 +172,7 @@ mingw-w64-x86_64-vulkan-headers 1.2.168-2
 mingw-w64-x86_64-vulkan-loader 1.2.166-1
 mingw-w64-x86_64-vulkan-validation-layers 1.2.162-3
 mingw-w64-x86_64-windows-default-manifest 6.4-3
-mingw-w64-x86_64-winpthreads-git 9.0.0.6144.45def5d7-1
+mingw-w64-x86_64-winpthreads-git 9.0.0.6154.e37b315b-1
 mingw-w64-x86_64-xxhash 0.8.0-1
 mingw-w64-x86_64-xz 5.2.5-2
 mingw-w64-x86_64-z3 4.8.9-1

readme.md

@@ -8,7 +8,7 @@
 - [OpenGL context configuration override](#opengl-context-configuration-override)
 - [How to set environment variables](#how-to-set-environment-variables)
 # Downloads
-Mesa 21.0.1 builds with Visual Studio and MSYS2 Mingw-w64 are now available in [releases section](https://github.com/pal1000/mesa-dist-win/releases).
+Mesa 21.0.2 builds with Visual Studio and MSYS2 Mingw-w64 are now available in [releases section](https://github.com/pal1000/mesa-dist-win/releases).
 # Known issues
 - 64-bit binaries in both MSVC and MinGW packages require a CPU with AVX even though they shouldn't
 
@@ -38,14 +38,15 @@ Same problem with same solution applies to osmesa if you are upgrading from 17.3
 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:
-- [llvmpipe](https://www.mesa3d.org/llvmpipe.html) 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](https://www.mesa3d.org/egl.html). File name: libglapi.dll. Required by llvmpipe, softpipe and swr if Mesa3D is built with shared glapi. Since 20.0.2 it is available in both MSVC and MSYS2 Mingw-w64 packages. 
-- [GLonD3D12](https://docs.mesa3d.org/drivers/d3d12.html). Standalone ICD filename: openglon12.dll. This driver introduced in 21.0.0 is operating as wrapper returning D3D12 API calls. Due to this nature it can use GPU accelleration. Select it via `GALLIUM_DRIVER=d3d12` environment variable, but note that it's only available in MSVC package. By default it requires at least 1 D3D12 capable GPU with driver, but it can be tested with WARP via `LIBGL_ALWAYS_SOFTWARE=1`. It also depends on DirectX IL for redistribution which can be installed via [deployment tools](#installation-and-usage). The standalone ICD only contains GLonD3D12 which means it always uses it without caring about GALLIUM_DRIVER value.
-- [zink](https://docs.mesa3d.org/drivers/zink.html). This driver introduced for Windows in 21.0.0 is operating as wrapper returning Vulkan API calls. Due to this nature it can use GPU accelleration. Select it via `GALLIUM_DRIVER=zink` environment variable, but note that it's only available in MinGW package. zink ignores Vulkan CPU type devices, so you can't test it with SwiftShader. zink requires at least 1 Vulkan device and Vulkan loader/[runtime](https://vulkan.lunarg.com/sdk/home#windows) to initialize.
-- [swr](https://openswr.org/). File names: swrAVX.dll, swrAVX2.dll, swrSKX.dll, swrKNL.dll. An alternative desktop OpenGL driver developed by Intel.  Available in MSVC package and since 20.1.7 in MinGW package as well. It only supports x64, x86 is [officially unsupported](https://bugs.freedesktop.org/show_bug.cgi?id=102564#c5). There are currently 4 DLLs, only one being loaded based on what the user CPU can do. 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](#how-to-set-environment-variables).
-- [OpenGL ES standalone drivers](https://www.mesa3d.org/opengles.html). 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. Since 20.0.2 they are available in both MSVC and MSYS2 Mingw-w64 packages.
+- [llvmpipe](https://www.mesa3d.org/llvmpipe.html). llvmpipe is a Desktop OpenGL software renderer intended as fallback when hardware acceleration is not possible. It can only handle very light gaming with good performance. This is the default Mesa3D desktop OpenGL driver when GLonD3D12 is either unavailable or fails to load. It's available for both x86 and x64 as part of Mesa3D Desktop OpenGL bundle `opengl32.dll`. When it's not the default driver select it by setting  environment variable `GALLIUM_DRIVER=llvmpipe`.
+- softpipe is a reference implementation of a Desktop OpenGL software renderer with no focus towards gaming performance. It's available for both x86 and x64 as part of Mesa3D Desktop OpenGL bundle `opengl32.dll`. Select it by setting  environment variable `GALLIUM_DRIVER=softpipe`.
+- [GLAPI shared library](https://www.mesa3d.org/egl.html). File name: libglapi.dll. Required by all Mesa3D OpenGL and OpenGL ES drivers if Mesa3D is built with shared glapi. Since 20.0.2 it is available in both MSVC and MSYS2 Mingw-w64 packages. 
+- [GLonD3D12](https://docs.mesa3d.org/drivers/d3d12.html). It's available for both x86 and x64 as part of Mesa3D Desktop OpenGL bundle `opengl32.dll` and standalone as `openglon12.dll` and it's only available in MSVC package. In addition to officially requiring Windows 10 v10.0.19041.488 or newer, it also depends on DirectX IL for redistribution - `dxil.dll` to load, which can be installed via [deployment tools](#installation-and-usage). When available and if it can load, this is the default Mesa3D desktop OpenGL driver on D3D12 GPU accelerated systems. This driver introduced in 21.0.0 is operating as wrapper returning D3D12 API calls. Due to this nature it can use GPU accelleration. If it's not selected by default you can test it with Direct3D WARP software renderer built into Windows by setting `GALLIUM_DRIVER=d3d12` and `LIBGL_ALWAYS_SOFTWARE=1` environment variables. The standalone copy doesn't need `GALLIUM_DRIVER=d3d12` being set and it can only be installed via system-wide deployment tool. The standalone GLonD3D12 and Mesa3D Desktop OpenGL bundle replace each other when using system-wide deployment tool but you can reverse it any time. 
+- [zink](https://docs.mesa3d.org/drivers/zink.html). This driver introduced for Windows in 21.0.0 it's available for both x86 and x64 as part of Mesa3D Desktop OpenGL bundle `opengl32.dll` and it's only available in MinGW package. Siimilarly to GLonD3D12, it operates as wrapper returning Vulkan API calls. Due to this nature it uses GPU accelleration. Select it via `GALLIUM_DRIVER=zink` environment variable, but note that it requires at least 1 Vulkan device and Vulkan loader/[runtime](https://vulkan.lunarg.com/sdk/home#windows) to initialize. zink ignores Vulkan CPU type devices, so you can't test it with SwiftShader.
+- [swr](https://openswr.org/). File names: swrAVX.dll, swrAVX2.dll, swrSKX.dll, swrKNL.dll. Even though it resides outside of Mesa3D Desktop OpenGL bundle `opengl32.dll` it still depends on it. This alternative desktop OpenGL software rendering driver developed by Intel is optimized for visualization software. It's available in MSVC package and since 20.1.7 in MinGW package as well. It only supports x64, x86 is [officially unsupported](https://bugs.freedesktop.org/show_bug.cgi?id=102564#c5). There are currently 4 DLLs, only one being loaded based on what the user CPU can do. You can switch to swr by setting GALLIUM_DRIVER environment variable value to swr.
+- [OpenGL ES standalone drivers](https://www.mesa3d.org/opengles.html). File names: libGLESv1_CM.dll and libGLESv2.dll. OpenGL ES 1.x, 2.x and 3.x standalone drivers available for 32-bit and 64-bit applications. Since 20.0.2 they are available in both MSVC and MSYS2 Mingw-w64 packages.
 - [osmesa](https://www.mesa3d.org/osmesa.html). File name: osmesa.dll. 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. Since 21.0.0 only osmesa gallium remained. It supports OpenGL 3.x and newer. Since 20.0.2 osmesa integration with standalone GLLES drivers is available in both MSVC and MSYS2 Mingw-w64 packages.
-- graw. File names: graw.dll, graw_null.dll. This is Mesa3D plug-in library. It is not a driver. Available for both x86 and x64 and in full (with window system support) and headless (no window) versions. This is used in special cases by software that is designed to use Mesa3D code internal APIs. Since 20.0.2 both full and headless versions are available in both MSVC and MSYS2 Mingw-w64 packages.
+- graw. File names: graw.dll, graw_null.dll. This is Mesa3D plug-in library mainly used by unit tests. It is not a driver. Available for both x86 and x64 and in full (with window system support) and headless (no window) versions. This is used in special cases by software that is designed to use Mesa3D code internal APIs. Since 20.0.2 both full and headless versions are available in both MSVC and MSYS2 Mingw-w64 packages.
 - SPIR-V to DXIL tool and library are only available in MSVC package since 21.0.0. File names: spirv_to_dxil.dll and spirv2dxil.exe.
 - test suite. Many executable unit tests.
 - libraries and headers generated at build time for both 32-bit and 64-bit builds are located 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.

releasenotes.md

@@ -1,9 +1,12 @@
-# Next release
+# 21.0.2
+- Updated Mesa3D to [21.0.2](https://docs.mesa3d.org/relnotes/21.0.2.html).
 ### Deployment
 - Add support for GLonD3D12 standalone driver in system wide deployment tool;
 - Avoid potential errors during uninstall in system-wide deployment tool.
-### Documentation
--  README: Add known issues section and drop obsolete info.
+### End-user documentation
+- Add known issues section;
+- Drop obsolete info;
+- Expand description of Mesa3D drivers available on Windows. See [#55](https://github.com/pal1000/mesa-dist-win/issues/55) and [#59](https://github.com/pal1000/mesa-dist-win/issues/59) for support tickets hinting that there is not enough info in documentation.
 ### Build script
 - Restore x64 llvm-config tool build as it's needed during build environment info dump.
 ### Debug tools