Graphics Environment Setup¶

About Graphics Environment ¶

Choreonoid renders robot and environment models using three-dimensional computer graphics (3DCG). To accomplish this, the graphics environment of the PC being used must meet the following requirements:

OpenGL (version 3.3 or higher), a three-dimensional rendering API, must be available
GPU hardware acceleration for OpenGL must be available

Regarding requirement 1, this is usually available on Supported Platforms. This requirement must first be met for Choreonoid to operate. Note that the rendering engine of Choreonoid uses the OpenGL 3.3 or later API and implements its rendering functions using GLSL, a programmable shader language.

Choreonoid works with OpenGL version 3.3 or higher, but in environments where a newer version is available, it also takes advantage of the newer features to perform more advanced rendering. In particular, in environments where OpenGL 4.5 or later is available, a technique called the “reversed depth buffer” is enabled, which greatly improves the rendering precision in the depth direction. With this, artifacts such as flickering of object surfaces (Z-fighting) are less likely to occur even in scenes where large and small objects coexist or in environment models covering a wide area. With a combination of a recent GPU and driver, OpenGL up to 4.6 is usually available and this feature is enabled automatically. In environments with OpenGL older than 4.5, the standard depth buffer is used instead, and a warning message to that effect is displayed on the message view at startup.

Additionally, to use Choreonoid comfortably, it is desirable that requirement 2 is also met. Otherwise, 3DCG rendering will become extremely slow, making it impractical unless you are using very simple models.

On Windows, OpenGL hardware acceleration is usually available in the state when the PC is purchased. However, please note that if you install Windows yourself or replace the video board, you may need to separately install graphics drivers for the installed GPU.

On Linux, open source drivers are well developed, and for many GPUs, OpenGL acceleration functions immediately after installation. However, for NVIDIA GPUs, the proprietary driver must be installed separately to achieve full performance. The situation for each GPU type is described later.

When using virtual machines, OpenGL hardware acceleration often does not function sufficiently. In such cases, rendering may be slow or may not render properly. This is a limitation on the virtual machine side. Generally, such situations are common with virtual machines, so their use is not highly recommended, and if you do use them, please do so with this understanding. There is a similar problem with WSL on Windows, which is described in the next section.

About the Use on WSL ¶

It seems that many people try to use Choreonoid on WSL (WSL2), which provides a Linux environment on Windows, but we cannot recommend using WSL from the viewpoint of the graphics environment.

The GUI function of WSL2 (WSLg) can display Linux GUI applications, and for OpenGL, a mechanism to utilize the GPU through the D3D12 backend of Mesa is nominally provided. In reality, however, this mechanism does not work in many environments, and the OpenGL rendering falls back to software rendering (llvmpipe). In this case, hardware acceleration does not work at all, and the rendering becomes extremely slow. Even when the D3D12 backend is enabled, there are restrictions on the available OpenGL features and versions, and problems such as corrupted rendering may occur. This situation has not been fundamentally improved so far, and there are continuing reports that the acceleration does not work at all with some combinations of GPUs and drivers.

You can check how the OpenGL rendering is performed on WSL with the glxinfo command described later. If “llvmpipe” is shown in the “OpenGL renderer string” entry, software rendering is being used.

As described above, there is practically no environment where hardware acceleration of OpenGL works properly on WSL, so WSL is not supported as an operating environment of Choreonoid. Even if problems such as slow or corrupted rendering occur on WSL, they are due to the restrictions of the graphics environment of WSL and cannot be addressed on the Choreonoid side. If you use Choreonoid on Windows, use the native Windows version. If you want to use the Linux version, we recommend using Ubuntu Linux installed on a real machine.

GPU Types ¶

GPU types can be broadly distinguished by manufacturer. Below is a brief summary of the situation for each GPU type.

NVIDIA GPUs (GeForce/RTX/Quadro, etc.)

They operate without problems and have excellent performance.

When seeking the highest performance, NVIDIA high-end models are currently strong candidates.

When using with Ubuntu, the proprietary driver must be separately installed to achieve full performance. How to install it is described later.

AMD GPUs (Radeon)

Recent models operate without problems.

On Linux, the open source driver (Mesa) included in Ubuntu as standard officially supports AMD GPUs, and hardware acceleration functions without installing an additional driver. The performance of the driver has also improved greatly in recent years.

Problems may occur with very old generations of models (those before the GCN architecture), so please avoid using them.

Intel GPUs (CPU integrated GPUs, Arc)

In addition to the GPUs integrated into Intel Core i-series and other CPUs (HD Graphics, UHD Graphics, Iris Xe, etc.), there are also the discrete GPUs of the Arc series. Both operate without problems.

Regarding rendering speed, the CPU integrated GPUs are basically not as fast as the discrete GPUs from the above two manufacturers, but they should be fine when using relatively simple models.

They operate without problems with the open source driver included in Ubuntu as standard.

However, older models of the CPU integrated GPUs may not render shadows properly. For such models, shadow rendering is disabled.

NVIDIA GPUs are recommended for use considering their track record, stability, performance, and other factors comprehensively. AMD GPUs are also sufficiently usable now that the drivers are stable. Intel CPU integrated GPUs do not have exceptional performance but operate stably, so if your PC is equipped with one, it would be good to try it first.

Installing GPU Drivers on Windows ¶

On Windows, appropriate drivers are often installed by default, so you usually don’t need to worry about this much. If three-dimensional model rendering in Choreonoid does not work properly, please check whether drivers are correctly installed.

Installing GPU Drivers on Ubuntu Linux ¶

On Linux, you may need to install GPU drivers separately. The methods are explained below for each GPU type.

For NVIDIA GPUs¶

For NVIDIA GPUs, you need to use the driver developed by NVIDIA (which is treated as a “proprietary driver” in the package management of Ubuntu). As it is developed by the manufacturer itself, its functionality and performance are excellent, and it makes the most of the capability of the GPU. If it is not installed, the open source driver called “Nouveau” is used, but this one is not recommended because hardware acceleration of 3D rendering does not function sufficiently with it.

Note that in recent versions of Ubuntu, when an NVIDIA GPU is detected during the OS installation, an option to install the NVIDIA driver together is provided (an item in the installer such as “Install third-party software for graphics and Wi-Fi hardware”). If you installed the OS with this option enabled, the NVIDIA driver is installed from the beginning and no additional work is required. You can check whether the driver is installed by executing the nvidia-smi command in a terminal and seeing whether the GPU information is displayed.

If the driver is not installed, it is reliable to install it from the packages provided in the official Ubuntu repository. Executing the following command in a terminal automatically selects and installs the driver recommended for the GPU in use.

sudo ubuntu-drivers install

The list of installable drivers can be checked with the following command.

ubuntu-drivers devices

The one marked with “recommended” here is the recommended driver. If you want to install a specific version, you can also install it by specifying the package name as follows.

sudo apt install nvidia-driver-595

(The 595 part is the version series of the driver.)

If you prefer a GUI, you can also perform the same installation from the “Additional Drivers” tab of the “Software & Updates” tool. The list of available drivers is displayed there, so select one with a newer version or one marked as “tested” if possible, and execute “Apply Changes”.

In either way, the driver becomes effective by restarting the PC after the installation.

Note

Recent NVIDIA drivers provide packages using the open source kernel modules (those with “-open” in the package names) in addition to the conventional proprietary kernel modules, and the former are recommended for relatively new generations of GPUs. If you use ubuntu-drivers install, the appropriate one is automatically selected according to the GPU.

Note

On PCs with Secure Boot enabled, you may be asked to set a password for module signing (MOK enrollment) when installing the driver. In that case, follow the instructions on the screen and enter the password on the screen displayed at the time of reboot to complete the enrollment.

For Intel GPUs¶

For Intel GPUs, the standard driver functions on Ubuntu Linux. This is an open source driver, but Intel itself is involved in the development, and there is no problem with its quality and performance. For Intel GPUs, you do not need to install a driver separately.

For AMD GPUs¶

For AMD GPUs, the standard open source driver (Mesa) functions on Ubuntu Linux, and you usually do not need to install a driver separately. In terms of performance, recent Mesa drivers are sufficiently fast.

There is also an AMD proprietary driver (AMDGPU-PRO) for computing purposes, but it is usually not necessary for rendering with Choreonoid. If the standard driver does not work well, obtain information from the official AMD website or the like.

How to Check OpenGL Version ¶

On Windows, the OpenGL version can be checked using configuration tools provided by GPU manufacturers.

On Ubuntu, it can be checked using the “glxinfo” command. This command is installed by executing

sudo apt install mesa-utils

Then, executing

glxinfo

displays information about OpenGL available in that environment. If this includes a line such as

OpenGL version string: 4.6.0 NVIDIA 595.71.05

it means OpenGL up to 4.6.0 is supported.

Alternatively, when Choreonoid starts, information like the following is output to the Message View, so you can also check it there.

OpenGL 4.6 (GLSL 4.60 NVIDIA) is available for Scene view.
Driver profile: NVIDIA Corporation NVIDIA GeForce RTX 5090/PCIe/SSE2 4.6.0 NVIDIA 595.71.05.

Here you can also check the information of the GPU and the driver in use.

How to Check GPU Performance ¶

When you press the “FPS test” button in the Configuration Dialog of the Scene View, an animation rotating the scene 360 degrees is performed and the frame rate required for this is displayed. This function shows the rendering speed, so you can check changes in rendering speed when changing GPUs or GPU drivers. It is recommended to perform the test with some model or project loaded and displayed.