Install the Intel® oneAPI Base Toolkit (Base Kit)

Install the Base Kit with the Intel® oneAPI DPC++/C++ Compiler selected as well as the automatic components the compiler adds. No other Base Kit components are required to be specified for Render Kit. See Base Kit product page for more information.

Install Tools to Build Samples

To build the Render Kit sample applications, you need to install CMake*, pkg-config library, and GNU* development tools. oneAPI tools and toolkits do not need the CMake and pkg-config, many oneAPI samples are provided as CMake projects and require CMake to build them. In some cases, pkg-config is also necessary to locate libraries needed to complete a build of the application.

Most compilers use GNU build toolchains existing on your system to provide a complete C/C++ development environment. If your Linux distribution does not include the complete suite of GNU development tools, you need to install them. Render Kit is validated with compilers that support C99 and C++11.

To install CMake, pkg-config, and GNU development tools on your Linux system, open a new terminal session and enter the following commands.

sudo apt update

sudo apt -y install cmake pkg-config build-essential

sudo yum update

sudo yum -y install cmake pkgconfig

sudo yum groupinstall "Development Tools"

sudo zypper update

sudo zypper --non-interactive install cmake pkg-config which

sudo zypper --non-interactive install patterns-devel-C-C++-devel_C_C++ gcc-c++

which cmake pkg-config make gcc g++

/usr/bin/cmake
/usr/bin/pkg-config
/usr/bin/make
/usr/bin/gcc
/usr/bin/g++

For more information about CMake, refer to CMake.org.

If you are cannot install CMake using your Linux distribution standard package manager, see the CMake download page for additional installation options.

Recommended: Update CMake*

Intel® Embree, Intel® OSPRay, Intel® Open Volume Kernel Library (Intel® Open VKL), and Intel® Open Image Denoise require CMake 3.1 or higher. Superbuild rkutil component requires CMake 3.12 or higher. For optimal compatibility with Intel® OSPRay Studio, CMake 3.15 or higher is suggested, but not required. To check what CMake version is installed on your system, run:

cmake --version

If your system package manager offers only a lower version CMake:

1. Remove the CMake installed on your system to avoid conflicting dependencies:
   • On Ubuntu:

     apt purge cmake

   • On CentOS or Red Hat:

     yum remove cmake

   • On SUSE:

     zypper rm cmake

2. Install the latest CMake version from the CMake download page with your preferred download method.

Install Graphics and Imaging Libraries

Some Render Kit samples, such as Intel OSPRay Studio, are interactive and require graphics libraries.

To install the graphics and imaging libraries, do one of the following depending on your Linux distribution:

sudo -E apt install libpng16-16 libjpeg-turbo8 libglfw3 libgl1 libopenimageio2.1 libxrandr2 libxinerama1 libxcursor1

sudo -E apt install libpng-dev libjpeg-turbo8-dev libglfw3-dev mesa-common-dev libopenimageio-dev libopenimageio-doc libxrandr-dev libxinerama-dev libxcursor-dev

sudo -E apt install libpng16-16 libjpeg-turbo8 libglfw3 libgl1 libopengl0 libopenimageio2.2 libxrandr2 libxinerama1 libxcursor1

sudo -E apt install libpng-dev libjpeg-turbo8-dev libglfw3-dev mesa-common-dev libopenimageio-dev libopenimageio-doc libxrandr-dev libxinerama-dev libxcursor-dev

sudo -E yum install libpng-devel.x86_64 libjpeg-turbo-devel.x86_64 glfw-devel.x86_64 libglvnd-devel.x86_64 OpenImageIO-devel.x86_64 libXrandr-devel.x86_64 libXinerama-devel.x86_64 libXcursor-devel.x86_64 libXxf86vm-devel

sudo -E yum install libpng-devel.x86_64 libjpeg-turbo-devel.x86_64 glfw-devel.x86_64 libglvnd-devel.x86_64 OpenImageIO-devel.x86_64 libXrandr-devel.x86_64 libXinerama-devel.x86_64 libXcursor-devel.x86_64 libXxf86vm-devel

The commands from the sections install the following libraries:

• libPNG is a PNG image loading library for input and output image files.
• libJPEG is a JPEG image loading library for input and output image files.
• libGL is OpenGL* graphics library.
• libGLFW3 is a multiplatform OpenGL API for windowing, input, events.
• libOpenImageIO is a library for reading and writing many image types, including HDR images.
• libxrandr is an X11* RandR* extension library.
• libXinerama is an X11* Xinerama* extension library.
• libxcursor is an X* cursor management library.
• libXxf86vm1 is an X11* XFree86* video mode extension library. This library is available on CentOS and Ubuntu by default.

Install OpenMP* Library

The oneAPI distribution of Intel ISPC has a dependency on OpenMP*. Other libraries in the rendering toolkit, such as OSPRay and OSPRay Studio, depend on Intel ISPC. Thus, OpenMP is required for precompiled and compiled programs built against Rendering Toolkit libraries to run.

To install an OpenMP library, do one of the following depending on your Linux distribution:

sudo -E apt install libomp-dev libomp5

sudo -E yum install libomp

sudo -E zypper install libomp-devel

sudo -E yum install libomp

Install Imaging Tools

Render Kit samples and applications often require preprocessed images as input or generate images as output. To display and convert input and output images, you need to get imaging tools for staging NetPBM filetypes (PPM and PFM). The ImageMagick* tool is suggested. See the ImageMagick website for standalone and package manager install instructions.

Set up System for GPU Compute

To work with GPU workloads, you need to configure your system properly.

stat -c "%G" /dev/dri/render*

groups ${USER}

sudo gpasswd -a ${USER} render

newgrp render

sudo sh -c "echo N> /sys/module/i915/parameters/enable_hangcheck"

Multi-card Deployments

Some systems may have compatibility issues between the system BIOS and the Linux kernel MMIO BAR re-allocation which prevents the Intel Data Center GPUs from being accessible once the system has booted. If you are experiencing problems with multi-card solutions and the Intel GPU devices not initializing (entries for the device are not enumerating in /dev/dri), you can work around the issue by adding pci=realloc=off to your kernel’s boot parameter.

To check if your system already has pci=realloc=off, you can check for the string via cat /proc/cmdline. If it does not, you can add the option using instructions provided by your operating system provider, or by editing the value of GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub to include pci=realloc=off. After you have made the changes, run sudo update-grub to regenerate the system’s boot configuration, and reboot.

After editing, the line for GRUB_CMDLINE_LINUX_DEFAULT should look similar to the following:

GRUB_CMDLINE_LINUX_DEFAULT="text pci=realloc=off"

After editing, make sure you run sudo update-grub and then reboot. After rebooting, you should now see pci=realloc=off in /proc/cmdline.

Install Level-Zero

If you did not install a graphics driver, OSPRay-based applications may still require level-zero. Download the level-zero-devel and level-zero release packages. Example download and install (as root user and using Ubuntu 22.04):

wget https://github.com/oneapi-src/level-zero/releases/download/v1.11.0/level-zero_1.11.0+u22.04_amd64.deb

wget https://github.com/oneapi-src/level-zero/releases/download/v1.11.0/level-zero-devel_1.11.0+u22.04_amd64.deb

dpkg -i level-zero*.deb

Set up Environment Variables

To use Render Kit from command line, you need to set up environment variables for Intel oneAPI Toolkit components using a setvars.sh script. You can find the script in the root folder of your Intel oneAPI Toolkit installation, which is by default /opt/intel/oneapi/ for sudo or root users and ~/intel/oneapi/ for non-root users.

Optional: Set up a Docker* Container for GUI Applications

If you want to run samples from a Docker* container, you need to configure the container environment first.

1. Give a Docker session access to a window manager using Xhost*. Allow access to the X* server:

   xhost +

   Otherwise, GUI-based Render Kit samples launched from the Docker container can give a X11: Failed to open display error.

2. Run the Docker container with one of the following methods:
   • With access to the display and X Server socket, but no access to GPU:
     • If you have proxy set up:

       sudo -E docker run --name renderkit --rm -it --privileged -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -e HTTP_PROXY=$HTTP_PROXY -e HTTPS_PROXY=$HTTPS_PROXY -e http_proxy=$http_proxy -e https_proxy=$https_proxy ubuntu bash

     • If you do not have proxy set up:

       sudo -E docker run --name renderkit --rm -it --privileged -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix ubuntu bash

   • With access to the display and X Server socket and to GPU:
     • If you have proxy set up:

       sudo -E docker run --name renderkit --rm -it --privileged --device=/dev/dri -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -e HTTP_PROXY=$HTTP_PROXY -e HTTPS_PROXY=$HTTPS_PROXY -e http_proxy=$http_proxy -e https_proxy=$https_proxy ubuntu bash

     • If you do not have proxy set up:

       sudo -E docker run --name renderkit --rm -it --privileged --device=/dev/dri -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix ubuntu bash

3. Install the Render Kit using a package manager or copy an offline installer into your docker container. See Intel oneAPI Toolkits Installation Guide for Linux* OS for instructions.
4. Run a GUI application, such as xclock, to verify the container can run GUI applications. Xclock is available as one of the following:
   • In the xorg-x11-apps package on CentOS/Red Hat
   • In the xclock package on SUSE
   • On the x11-apps on Ubuntu

Optional: Install Tools to Navigate Repositories and Documentation

You might need the following tools:

• Install Git* or Wget* to get the library and sample source code.
• Install Grip* and Mozilla* Firefox* to view documentation in Markdown format located in the Intel oneAPI Toolkit package or GitHub* repositories.
• Install a PDF viewer, for example, Evince*, to view in-package documentation.

Next Steps

Get started with the Intel® Rendering Toolkit by building and running sample applications.

Feedback on Issues

Share your feedback on this article in the Intel® Rendering Toolkit forum.