View source in Mesa

OpenSWR

A High Performance, Highly Scalable Software Rasterizer for OpenGL

Windows Build Instructions

The instructions below describe how to build Mesa with OpenSWR for Windows.

On Windows, OpenSWR is built using the Meson package as described in Mesa's installation page.

As of March 2022, OpenSWR has been moved to the Amber branch of Mesa. This walkthrough uses the Amber branch (21.3.x), as committed to Mesa 21.3.7. OpenSWR has been removed from the primary Mesa branch. The Mesa 22.x branch and higher has OpenSWR removed. Review the latest Mesa branches for more information.

  1. Prerequisites
    1. Download and Install Prerequisite Tools
    2. Download, Build, and Install LLVM
  2. Build Mesa with OpenSWR
  3. Using Mesa with OpenSWR

Prerequisites

Building Mesa with OpenSWR requires:

These instructions describe acquisition of all above prerequisites except Microsoft Visual Studio.

Note: 32-bit builds of Mesa with OpenSWR are possible but not described here. Use 32-bit targeting from Microsoft Visual Studio and LLVM to build Mesa with OpenSWR 32-bit.

Download and Install Prerequisite Tools

CMake

LLVM requires CMake to build and install. CMake is available for Windows as an executable installer on CMake's download page. The latest version should be fine. CMake is also distributed with Microsoft Visual Studio 2019.

Archive Tool

You will need a utility that can open and decompress tar.gz and/or tar.xz files. An easy-to-use (and free) graphical option for Windows is 7-zip, available on 7-zip's download page.

Chocolatey

Chocolatey is an easier way to get Mesa build time dependencies deployed. Install Chocolatey. Follow the Installing Chocolatey instructions.

Install Mesa build requirements from Chocolatey from a Command Prompt. You may wish to run this Command Prompt with Administrator Privileges (Right Click->Run As Administrator):

choco.exe install python3 winflexbison pkgconfiglite

Python 3

Install Python 3 via one of these options:

The walkthrough uses the Python 3.10 standalone.

Meson

Mesa with OpenSWR uses the Meson package to build and install. Meson is available to download and install via the Python 3 pip utility. The latest version should be fine. Meson 0.61.2 is used in this walkthrough.

Install Meson from a Command Prompt. You may wish to run this Command Prompt with Administrator Privileges (Right Click->Run As Administrator). The Python 3 pip.exe utility is found in the Python 3 Scripts directory. Install Meson via pip:

pip.exe install meson mako

Git

Install Git or look for it as distributed with Microsoft Visual Studio.

Download, Build, and Install LLVM

Mesa with OpenSWR relies on LLVM, so you will need to build and install it first if you do not already have it. The Mesa build relies the llvm-config.exe utility. llvm-config.exe does not ship with precompiled releases of LLVM at time of publication. Build LLVM to generate all needed LLVM tools to build Mesa. Please refer to the LLVM Windows build instructions with Visual Studio for a general overview, located here.

This walkthrough uses LLVM 12.0.1 (llvm-12.0.1.src.tar.xz). LLVM 13 was observed to fail when building the Mesa Amber branch.

Once LLVM source is downloaded and decompressed, create a build directory to contain the built LLVM distribution. In this example, we build both the release and debug version of LLVM, though you can choose to only have one or the other.

The Mesa Windows Meson build has the peculiarity that you cannot mix debug and release versions of libs (see link error LNK2038). If you are planning of building both versions of Mesa, you should also build both versions of LLVM. Below, it is assumed that we are building both.

Suppose we have LLVM extracted to C:\LLVM\src with build directories C:\LLVM\build-release and C:\LLVM\build-debug. We will install to C:\LLVM\install-release and C:\LLVM\install-debug, respectively.

Launch a fresh x64 Native Tools Command Prompt for VS 2019. You may wish to run this Command Prompt with Administrator Privileges (Right Click->Run As Administrator). Use cmake to generate MSVC .sln files, as follows: The release version:

cd C:\LLVM\build-release
cmake -D CMAKE_GENERATOR_PLATFORM=x64 ^
      -D LLVM_TARGETS_TO_BUILD=X86 ^
      -D LLVM_ENABLE_RTTI=1 ^
      -D LLVM_USE_CRT_DEBUG=MTd ^
      -D LLVM_USE_CRT_RELEASE=MT ^
      -D LLVM_ENABLE_TERMINFO=OFF ^
      -D CMAKE_INSTALL_PREFIX=C:\LLVM\install-release ^
      -Thost=x64 ^
      C:\LLVM\src
cmake --build . --config Release -Thost=x64
cmake --build . --config Release --target install -Thost=x64

and the debug version:

cd C:\LLVM\build-debug
cmake -D CMAKE_GENERATOR_PLATFORM=x64 ^
      -D LLVM_TARGETS_TO_BUILD=X86 ^
      -D LLVM_ENABLE_RTTI=1 ^
      -D LLVM_USE_CRT_DEBUG=MTd ^
      -D LLVM_USE_CRT_RELEASE=MT ^
      -D LLVM_ENABLE_TERMINFO=OFF ^
      -D CMAKE_INSTALL_PREFIX=C:\LLVM\install-debug ^
      -Thost=x64 ^
      C:\LLVM\src
cmake --build . --config Debug -Thost=x64
cmake --build . --config Debug --target install -Thost=x64

Note that, in theory, you only need to use one of LLVM_USE_CRT_DEBUG or LLVM_USE_CRT_RELEASE, depending on whether you are building Debug or Release, but it doesn't hurt to always include both in the cmake line.

Time and Space

On an Intel® Core™ i7-8665U Processor, build time for Release mode may be approximately 45 minutes. Intel® Xeon® based systems with larger caches are expected to build LLVM significantly faster. The build and install directories required less than 3 GB of disk space for release mode on the walkthrough system. The debug build requires significantly more disk storage (10s of GB).

Build Mesa with OpenSWR

If not already using the previous x64 Native Tools Command Prompt for VS 2019, launch a fresh instance. You may wish to run this Command Prompt with Administrator Privileges (Right Click->Run As Administrator).

If your system is behind a proxy then set the proxy. Many challenging connectivity errors may occur if the proxy is not set:

set HTTP_PROXY=<http://your.proxy:port>
set HTTPS_PROXY=<http://your.proxy:port>

Clone the mesa repo. Full instructions are available on Mesa's repository page.

git clone --no-checkout https://gitlab.freedesktop.org/mesa/mesa.git mesa
cd mesa
git checkout mesa-21.3.7

Add the Meson directory to your PATH. Meson is typically in your Scripts subfolder of the Python directory:

set PATH=<Path-to-Meson>;%PATH%

When building Mesa with OpenSWR, you must specify where LLVM is installed. In doing this, we can also specify the type of build. For a debug Mesa build, link to the debug LLVM installation. Similarly, use a release LLVM for building release Mesa. For release builds, add the release llvm-config.exe directory to your path.:

set PATH=C:\LLVM\install-release\bin;%PATH%

and for debug builds:

set PATH=C:\LLVM\install-release\bin;%PATH%

Create the Release build files:

mkdir build
meson setup --backend=vs2019 build/ \
-Dswr-arches=avx,avx2 \
-Dbuildtype=release \
-Dgallium-drivers=swrast,swr \
-Dvulkan-drivers= \
-Ddri-drivers= \

If you want to compile OSMesa (for off-screen rendering support), add -Dosmesa=true to the setup. Example:

meson setup --backend=vs2019 build/ \
-Dswr-arches=avx,avx2 \
-Dbuildtype=release \
-Dgallium-drivers=swrast,swr \
-Dvulkan-drivers= \
-Ddri-drivers= \
-Dosmesa=true

Important: Systems with Advanced Vector Extenstions 512 (AVX 512) support should add AVX 512 support to their configuration with the skx flag:

-Dswr-arches=avx,avx2,skx

Note: Check your target system architectural capabilities by visiting the Intel ARK database.

To see your Mesa build configuration:

meson configure build

To build Mesa with OpenSWR:

meson compile -C build

On an Intel® Core™ i7-8665U Processor, build time for Release mode may be approximately 30 minutes. Intel® Xeon® based systems with larger caches are expected to build LLVM significantly faster. The release build and install directories required less than 500 MB of disk space for release mode on the walkthrough system.

Deploy Mesa to your preferred directory:

meson install -C build --destdir C:\swr

Troubleshoot

Systems with prebuild issues related to ZLIB are typically seeing connectivity or proxy issues. Check your proxy settings. Use fresh, unaltered Mesa build directories. Try again.

Using Mesa with OpenSWR

The -Dosmesa=true, avx, avx2 build results in these library files:

Runtime libraries:

bin\libgallium_wgl.dll
bin\opengl32.dll
bin\osmesa.dll
bin\swrAVX.dll
bin\swrAVX2.dll
bin\z.dll

Header files:

include\GL\gl.h
include\GL\glcorearb.h
include\GL\glext.h
include\GL\osmesa.h
include\KHR\khrplatform.h
include\zconf.h
include\zlib.h

Stub link libraries and pkgconfig references:

lib\libgallium_wgl.lib
lib\opengl32.lib
lib\osmesa.lib
lib\pkgconfig\osmesa.pc
lib\pkgconfig\zlib.pc
lib\swrAVX.lib
lib\swrAVX2.lib
lib\z.lib

Application configuration file:

share\drirc.d\00-mesa-defaults.conf

To make these libraries usable across the system, first make a backup of any libraries listed in 'Runtime Libraries' in C:\Windows\system32, then place the above DLLs in C:\Windows\system32. If you plan to just run simple command line tests, you can simply place them in your application or current directory.

To use Mesa with OpenSWR, you will need to set OpenSWR as the gallium driver to use with the GALLIUM_DRIVER environment variable:

set GALLIUM_DRIVER=swr

Without this environment variable set, the default Mesa llvmpipe driver will be used.

Instrument OpenSWR-based applications with useful environment variables. In particular, review the GALLIUM_ prefixed variables. Refer to the enviornment variable document on mesa3d.org for details on variables like:

GALLIUM_HUD
GALLIUM_LOG_FILE
GALLIUM_PRINT_OPTIONS
GALLIUM_DUMP_CPU
LIBGL_ALWAYS_SOFTWARE

To send any runtime information to stderr, ensure GALLIUM_PRINT_OPTIONS is set!:

set GALLIUM_PRINT_OPTIONS=1

SWR_PRINT_INFO can cause the runtime to emit SWR status. Documentation is limited since OpenSWR has moved to the Amber Branch. You may set it before running a program:

set SWR_PRINT_INFO=1

Look for a message like:

SWR detected AVX2 instruction support (using: swrAVX2.dll).

Hello GL Quickstart

Many users employ the glxgears and glxinfo from the Mesa demos repository to check that their distribution of Mesa is running. Note: The performance advantages of OpenSWR tend to be realized in scenes with much more geometry than glxgears. View the Mesa demos for more information.

To try these applications you may wish to build them in an MinGW environment as the MSVC build path is not maintained (per the CMakeLists.txt file). For a hint to build wglinfo from within the Mesa Demos repository, this shorthand command was used on the walkthrough system:

cl wglinfo.c ..\xdemos\glinfo_common.c ..\glad\src\glad.c ..\glad\src\glad_wgl.c -I..\glad\include -I..\xdemos "C:\Program Files (x86)\Windows Kits\10\Lib\10.0.19041.0\um\x64\gdi32.lib" "C:\Program Files (x86)\Windows Kits\10\Lib\10.0.19041.0\um\x64\user32.lib" C:\swr\lib\opengl32.lib /Fe:wglinfo.exe

There also may be quick to build windows ports of glxgears and glinfo on Github.

OpenSWR maintained by OpenSWR
For information about compiler optimizations, see our Optimization Notice.
©2009-2022 Intel Corporation
Privacy