About GPU

Zivid SDK requires a GPU on the host machine to run optimally. Both integrated and dedicated GPUs can work well with Zivid, where the difference in performance lies in the capture time you get.

GPU Requirements

For optimal performance, the dedicated or integrated GPU should have at least 3 GB of RAM available. Additionally, an OpenCL driver (1.2 or later) for the GPU is necessary to use Zivid. Follow the instructions below for your specific GPU.

The OpenCL driver is usually installed together with the graphics driver, and should already be installed on Windows. Use the dropdown below if you want to check which GPU driver you have. If not, download and install the latest graphics driver from Intel.

Check GPU driver

Use Intel Driver & Support assistant to automatically detect your driver version or follow the instructions below to find it manually.

Screenshot of Intel Driver & Support Assistant Screenshot of the Graphics pane in "Intel Driver & Support Assistant"
  1. StartControl Panel

  2. Select Device Manager from the list (switch View by to Small Icons if needed)

  3. Expand the Display Adapter section and right-click Properties on your Intel® Display Adapter

  4. Navigate to the Driver tab and note the Driver Version presented

    Screenshot of the driver properties for the Intel graphics card on Windows.

After installing the graphics drivers, open Zivid Studio and verify that you do not get OpenCL errors.

Note

NVIDIA GPUs must have a compute capability higher than a minimum required value of 3.3. If this requirement is not fulfilled, the SDK will throw an exception:

The compute capability X.Y of the NVIDIA compute device is lower than the minimum required compute capability 3.3 (or The minimum required SM version is 3.3. Device has version X.Y).

An overview of NVIDIA GPUs and their corresponding compute capability can be found in https://developer.nvidia.com/cuda-gpus.

The OpenCL driver is usually installed together with the graphics driver. Use the dropdown below if you want to check which GPU driver you have. If not, download and install the relevant graphics driver for your GPU from NVIDIA.

Check GPU driver

Use NVIDIA Smart Scan to automatically detect your driver version or follow the instructions below to find it manually.

  1. Open NVIDIA Control Panel (right-click on Desktop).

  2. Click System Information (bottom-left corner).

  3. Note the Driver version in the Details section.

    Screenshot of NVIDIA system information on Windows.

After installing the graphics drivers, open Zivid Studio and verify that you do not get OpenCL errors.

Warning

Since SDK 2.10, support for AMD has been removed due to OpenCL stability issues in the drivers. It is possible to opt in to run the SDK with an unsupported compute device, by enabling an option in the Config.yml file. However, such a setup may give unexpected results and errors, and is not tested by Zivid.

Warning

Radeon no longer supports SPIR on some GPUs, please verify that your GPU drivers support SPIR to be compatible with Zivid.

The OpenCL driver is usually installed together with the graphics driver. Use the dropdown below if you want to check which GPU driver you have. If not, download and install the relevant graphics driver for your GPU from AMD.

Check GPU driver

Use AMD Driver Auto-detect tool to automatically detect your driver version or follow the instructions below to find it manually.

  1. Open AMD Radeon Settings (right-click on Desktop).

  2. Click on System to access the system overview, software and hardware details.

  3. Select the Software tab for detailed information about the installed graphics driver. Note the Driver Packaging Version.

Screenshot of AMD system information on Windows.

After installing the graphics drivers, open Zivid Studio and verify that you do not get OpenCL errors.

The graphics driver for Intel should already be installed on Ubuntu, but not necessarily the OpenCL driver. Use the dropdown below if you want to check if your graphics driver is present.

Check GPU driver

Open a terminal window by pressing Ctrl + Alt + T keys on the keyboard, and check if the driver is present.

lspci -k | grep -EA3 'VGA|3D|Display'

For more information, visit the official Intel pages.

  1. Open a terminal window by pressing Ctrl + Alt + T keys on the keyboard, and install the OpenCL driver.

    sudo apt update
    sudo apt install intel-opencl-icd
    
    sudo apt update
    sudo apt install intel-opencl-icd
    

    Note

    Support for Ubuntu 18.04 is removed since SDK 2.10. To see Ubuntu 18.04 instructions for an earlier SDK version, change the Knowledge Base version in the top left corner.

  2. Open Zivid Studio and verify that you do not get OpenCL errors.

Note

If you get OpenCL errors, you might have to add your user to group Video.

Note

NVIDIA GPUs must have a compute capability higher than a minimum required value of 3.3. If this requirement is not fulfilled, the SDK will throw an exception:

The compute capability X.Y of the NVIDIA compute device is lower than the minimum required compute capability 3.3 (or The minimum required SM version is 3.3. Device has version X.Y).

An overview of NVIDIA GPUs and their corresponding compute capability can be found in https://developer.nvidia.com/cuda-gpus.

The OpenCL driver for NVIDIA is installed with the graphics driver. Use the dropdown below if you want to check if your graphics driver is present, or continue to install the latest driver for your system.

Check GPU driver

Open a terminal window by pressing Ctrl + Alt + T keys on the keyboard, then execute the following command:

nvidia-smi

This will print the driver version.

  1. Add the NVIDIA GPU driver PPA to your system:

    Open a terminal window by pressing Ctrl + Alt + T keys on the keyboard, and add the graphics-driver PPA.

    sudo add-apt-repository ppa:graphics-drivers/ppa
    

    This will provide info on the current long-lived branch release nvidia-xxx.

  2. Install the latest drivers for your system:

    sudo apt update
    sudo apt install nvidia-driver-xxx
    
    sudo apt update
    sudo apt install nvidia-driver-xxx
    

    Note

    Support for Ubuntu 18.04 is removed since SDK 2.10. To see Ubuntu 18.04 instructions for an earlier SDK version, change the Knowledge Base version in the top left corner.

    After installing the driver, reboot your system.

    sudo reboot
    
  3. Open Zivid Studio and verify that you do not get OpenCL errors.

Note

If you get OpenCL errors, you might have to add your user to group Video.

Warning

Since SDK 2.10, support for AMD has been removed due to OpenCL stability issues in the drivers. It is possible to opt in to run the SDK with an unsupported compute device, by enabling an option in the Config.yml file. However, such a setup may give unexpected results and errors, and is not tested by Zivid.

Warning

Radeon no longer supports SPIR on some GPUs, please verify that your GPU drivers support SPIR to be compatible with Zivid.

  1. Download and extract the correct Radeon Software for Linux:

    Open a terminal window by pressing Ctrl + Alt + T keys on the keyboard, and create a temporary folder.

    mkdir amd && cd amd
    

    If you go to https://www.amd.com/en/support/kb/release-notes/rn-amdgpu-unified-linux-22-20 you will find a link to a version AMD GPU driver installer which is broken. In the following instructions we will use a version that we have tested and that works. At the time of writing this is version 22.20.3. AMD has a /latest path, but this still points to 22.20, which is broken.

    wget --referer http://support.amd.com http://repo.radeon.com/amdgpu-install/22.20.3/ubuntu/jammy/amdgpu-install_22.20.50203-1_all.deb
    

    Install this package with apt:

    sudo apt update
    sudo apt install ./amdgpu-install_22.20.50203-1_all.deb
    

    Check your Linux Kernel version:

    uname -r
    

    For Linux Kernel version 5.4 (Ubuntu LTS), download Radeon Software 20.45 for Ubuntu 20.04:

    wget --referer http://support.amd.com https://drivers.amd.com/drivers/linux/amdgpu-pro-20.45-1188099-ubuntu-20.04.tar.xz
    

    Extract the contents:

    tar -Jxvf amdgpu-pro-20.45-1188099-ubuntu-20.04.tar.xz
    cd amdgpu-pro-20.45-1188099-ubuntu-20.04
    

    For Linux Kernel version 5.8 (Ubuntu LTS HWE stacks), download Radeon Software 20.50 for Linux 20.04:

    wget --referer http://support.amd.com https://drivers.amd.com/drivers/linux/amdgpu-pro-20.50-1234664-ubuntu-20.04.tar.xz
    

    Extract the contents:

    tar -Jxvf amdgpu-pro-20.50-1234664-ubuntu-20.04.tar.xz
    cd amdgpu-pro-20.50-1234664-ubuntu-20.04
    

    Note

    Support for Ubuntu 18.04 is removed since SDK 2.10. To see Ubuntu 18.04 instructions for an earlier SDK version, change the Knowledge Base version in the top left corner.

  2. Install the graphics stack:

    AMDs own instructions

    amdgpu-install --usecase=graphics,opencl --no-32 --no-dkms
    

    Note

    If you require Secure Boot you may have to include DKMS (remove --no-dkms in the above command). For more information see secure-boot-support.

    Now add your user as member of both the render group and the video group.

    sudo gpasswd -a $USER render
    sudo gpasswd -a $USER video
    

    You may have to reboot in order for the changes to take effect.

    sudo reboot
    

    You may now try to open Zivid Studio. If it fails then follow the next steps.

    AMDs own instructions.

    ./amdgpu-pro-install --opencl=pal
    

    Note

    Support for Ubuntu 18.04 is removed since SDK 2.10. To see Ubuntu 18.04 instructions for an earlier SDK version, change the Knowledge Base version in the top left corner.

  3. Follow the steps to Configure Secure Boot (if prompted):

    ../../_images/secure_boot_1.png
    ../../_images/secure_boot_2.png
    ../../_images/secure_boot_3.png

    If you are not able to boot, check System Boot Error After AMD OpenCL Drivers Installation.

  4. Open Zivid Studio and verify that you do not get OpenCL errors.

Note

If you get OpenCL errors, you might have to add your user to group Video.

An OpenGL driver (3.0 or later) for the GPU is necessary to use Zivid Studio or visualizers in the SDK. These should be installed with the GPU drivers, but if you have old drivers they may use a version below 3.0. Follow the instructions in the dropdown below to check which OpenGL version you have.

Check OpenGL drivers
  1. Download OpenGL Extensions Viewer.

  2. Install it, launch it, and check the OpenGL version:

    ../../_images/opengl_version_windows_screenshot.png

In case the version is below 3.0, you need to install the latest GPU driver. Follow the instructions for installing OpenCL drivers above.

Open a terminal window by pressing Ctrl + Alt + T keys on the keyboard, then execute the following commands:

sudo apt install mesa-utils
glxinfo | grep "OpenGL version"

This will print the OpenGL version.

../../_images/opengl_version_ubuntu_screenshot.png

In case the version is below 3.0, you need to install the latest GPU driver. Follow the instructions for installing OpenCL drivers above.

Performance Considerations

It is also the best choice if the GPU will be used for more than Zivid’s computations. A medium to high-end NVIDIA GPU with at least 3 GB of memory is required for optimal performance. This is the preferred solution for Zivid.

Recommendations:

  • NVIDIA GeForce GTX 1060 or better for desktops

  • NVIDIA GeForce MX150 or better for laptops

The benefit of an integrated GPU is that the data transfer from GPU to CPU is fast. It is also beneficial for applications that require low power consumption, e.g., battery-powered mobile platforms. A high-end integrated GPU with at least 3 GB of memory available is required for optimal performance.

Recommendations:

  • Intel i7 with HD630 or better

Selecting Compute Device

If you have multiple GPUs and want Zivid SDK to use a specific one, you can specify the compute device in the Configuration file. This is also the case if you want to use Zivid SDK with a CPU.

If the file does not already exist, download the Config.yml file and place it in the following directory:

mkdir %LOCALAPPDATA%\Zivid\API
move %HOMEPATH%\Downloads\Config.yml %LOCALAPPDATA%\Zivid\API\
mkdir --parents "${XDG_CONFIG_HOME-$HOME/.config}"/Zivid/API
mv ~/Downloads/Config.yml "${XDG_CONFIG_HOME-$HOME/.config}"/Zivid/API/

The desired GPU is assigned by changing the ComputeDevice parameters in the configuration file.

If you have multiple GPUs from a single vendor (e.g. two Nvidia GPUs), SelectionFilter must specify which GPU to use. We will use clinfo to list all compute devices. Follow the dropdown below for more information about clinfo, how to install it and how to use it.

clinfo
  1. Download the clinfo Windows binary file.

  2. Launch the Command Prompt by pressing Win + R keys on the keyboard, then type cmd and press Enter.

    ../../_images/run-cmd-windows.png
  3. Navigate to the directory that contains the downloaded file (clinfo.exe) and execute the following command:

    clinfo.exe -l
    

    This will print all available information about all OpenCL platforms on the system and the devices they expose.

    ../../_images/cmd_cl_windows.png

    If your GPU is not listed you may need to install the OpenCL drivers and/or graphics drivers.

  4. To check the OpenCL driver version, use clinfo and search for the OpenCL platform version:

    clinfo.exe | findstr "Platform\ Version"
    

    If the version is below OpenCL 1.2, you need to update your graphics drivers.

  1. Open a terminal window by pressing Ctrl + Alt + T keys on the keyboard and install clinfo.

    sudo apt install -y clinfo
    
  2. Run clinfo -l to list all OpenCL platforms.

    sudo /usr/bin/clinfo -l
    

    This will print all available information about all OpenCL platforms on the system and the devices they expose.

    If your GPU is not listed you may need to install the OpenCL drivers and/or graphics drivers.

    ../../_images/no-platforms-ubuntu.png
  3. To check the OpenCL driver version, use clinfo and search for the OpenCL platform version:

    sudo /usr/bin/clinfo | grep "Platform Version"
    

    If the version is below OpenCL 1.2, you need to update your OpenCL drivers and/or graphics drivers.

To find the specific GPU name, run clinfo to list your compute devices.

clinfo -l

Change the SelectionFilter in the configuration file to be any unique part of the name of the desired device. For example, for the NVIDIA GeForce RTX 3060 in the following output

../../_images/clinfo_multiple_gpu_single_vendor.png

you would set SelectionFilter to

ComputeDevice:
    SelectionFilter: "RTX 3060"
    Type: Any
    Vendor: Any

If you have multiple GPUs from multiple vendors (e.g. an integrated Intel GPU and a dedicated NVIDIA GPU), change Type to GPU and Vendor to NVIDIA or Intel, e.g.

ComputeDevice:
    SelectionFilter: ""
    Type: GPU
    Vendor: NVIDIA

Enabling unsupported compute devices

Enabling unsupported compute devices can be done by enabling an option in the Configuration file. However, such a setup may give unexpected results and errors, and is not tested by Zivid. Currently, the unsupported compute devices are CPUs and AMD GPUs.

If the file does not already exist, download the Config.yml file and place it in the following directory:

mkdir %LOCALAPPDATA%\Zivid\API
move %HOMEPATH%\Downloads\Config.yml %LOCALAPPDATA%\Zivid\API\
mkdir --parents "${XDG_CONFIG_HOME-$HOME/.config}"/Zivid/API
mv ~/Downloads/Config.yml "${XDG_CONFIG_HOME-$HOME/.config}"/Zivid/API/

The config file contains the following information, where AllowUnsupported: yes enables unsupported compute devices:

__version__:
    serializer: 1
    data: 19
Configuration:
    ComputeDevice:
        AllowUnsupported: yes

Enable CPU

Warning

Capture time will be greatly increased when using CPU and is not a recommended mode for most applications.

It is possible to run the Zivid SDK on an Intel chipset using their CPU Runtime for OpenCL. Modify the compute device Type to be CPU in the Config.yml.

__version__:
    serializer: 1
    data: 19
Configuration:
    ComputeDevice:
        Type: CPU
        AllowUnsupported: yes