Configure Your System
To use the
Intel® oneAPI Rendering Toolkit
(Render Kit) samples, you first need to set up your system as follows:
- Install the oneAPI sample browser to access sample sources.
- Install tools to build the samples.
- Recommended: Update CMake*.
- Install graphics and imaging libraries to view interactive sample application.
- Install imaging tools to work with sample input and output.
- Optional: Set up system to analyze GPU.
- Optional: Set up a Docker* container for GUI-based applications.
- Optional: Install tools to navigate repositories and documentation.
If you use the Render Kit from the Intel® DevCloud, you can skip the configuration and start with
building and running sample applications. Intel DevCloud already has all the Render Kit components installed and configured. See
Get Started with Intel DevCloud for oneAPI for details.
Install the oneAPI Sample Browser
You can access sample applications from the oneAPI sample browser. The browser is distributed as part of the
Intel® oneAPI Base Toolkit
(Base Kit
) in the
dev-utilities
directory.
Install the
Base Kit
with
Intel® oneAPI Threading Building Blocks
, which is available in both Render Kit and
Base Kit
. No other
Base Kit
components are required. See
Base Kit
product page for more information and download links.
You can also get the samples manually using
Git*.
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.
You need root permissions to install the tools.
Ubuntu*
sudo apt update
sudo apt -y install cmake pkg-config build-essential
Red Hat*, Fedora*, CentOS*
sudo yum update
sudo yum -y install cmake pkgconfig
sudo yum groupinstall "Development Tools"
SUSE*
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++
For all distributions: Verify the installation
Print the installation location with this command:
which cmake pkg-config make gcc g++
One or more of these locations will display:
/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. Intel® OSPRay Studio requires CMake 3.15 or higher. To check what CMake version is installed on your system, run:
cmake --version
If your system package manager offers only a lower version CMake:
- 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
- Install the latest CMake version from theCMake 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:
You need root permissions to install the libraries.
Ubuntu 18.04 Runtime Dependencies
sudo -E apt install libpng16-16 libjpeg-turbo8 libglfw3 libgl1 libopenimageio1.7 libxrandr2 libxinerama1 libxcursor1
Ubuntu 18.04 Developer Build Dependencies
sudo -E apt install libpng-dev libjpeg-turbo8-dev libglfw3-dev mesa-common-dev libopenimageio-dev libopenimageio-doc libxrandr-dev libxinerama-dev libxcursor-dev
Ubuntu 20.04 Runtime Dependencies
sudo -E apt install libpng16-16 libjpeg-turbo8 libglfw3 libgl1 libopenimageio2.1 libxrandr2 libxinerama1 libxcursor1
Ubuntu 20.04 Developer Build Dependencies
sudo -E apt install libpng-dev libjpeg-turbo8-dev libglfw3-dev mesa-common-dev libopenimageio-dev libopenimageio-doc libxrandr-dev libxinerama-dev libxcursor-dev
CentOS 8 Runtime Dependencies
- Make sure extended library sets are searchable:sudo -E yum install epel-release dnf-plugins-coresudo -E yum config-manager --set-enabled powertoolssudo -E yum repolist
- Install graphics drives:sudo -E yum install mesa-dri-drivers.x86_64
- Install runtimes:sudo -E yum install libpng.x86_64 libjpeg-turbo.x86_64 glfw.x86_64 libglvnd-glx.x86_64 OpenImageIO.x86_64 libXrandr2.x86_64 libXinerama.x86_64 libXcursor.x86_64
CentOS 8 Developer Build Dependencies
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
openSUSE* Leap 15 SP2 Runtime Dependencies
- Install graphics drives:sudo -E zypper install Mesa-dri
- Install runtimes:sudo -E zypper install libpng16-16 libjpeg8 libglfw3 libglvnd OpenImageIO libXrandr2 libXinerama1 libXcursor1 libXxf86vm1
openSUSE* Leap 15 SP2 Developer Build Dependencies
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
In the repository, the
libopenimageio
can have a different label or version for your OS distribution.
dev[el]
-suffixed packages are used for building, while non-dev[el]
packages are used at application run-time.
The
commands from the sections install
the following libraries:
- libPNGis a PNG image loading library for input and output image files.
- libJPEGis a JPEG image loading library for input and output image files.
- libGLis OpenGL* graphics library.
- libGLFW3is a multiplatform OpenGL API for windowing, input, events.
- libOpenImageIOis a library for reading and writing many image types, in particular, HDR images.
- libxrandris an X11* RandR* extension library.
- libXineramais an X11* Xinerama* extension library.
- libxcursoris an X* cursor management library.
- libXxf86vm1is an X11* XFree86* video mode extension library. This library is available on CentOS and Ubuntu by default.
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). Recommended tool is ImageMagick*. See the
ImageMagick website for standalone and package manager install instructions.
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.
If you installed the Intel oneAPI Toolkits to a different location, make sure to replace the default path with your custom one in the commands below before running them.
Option 1. Configure environment variables once per session
Each time as you open a new terminal, you need to source the
setvars.sh
script as follows:
- For root or sudo users:source /opt/intel/oneapi/setvars.sh
- For non-root users:source ~/intel/oneapi/setvars.sh
Option 2. Configure environment variables to be set up automatically for all sessions
To have the environment automatically set up for your all projects, add the source command to a startup script where it will be invoked automatically.
For example, you can add the
source /opt/intel/oneapi/setvars.sh
(for root users) or the
source ~/intel/oneapi/setvars.sh
(for non-root users) command to your
~/.bashrc_profile
or
~/.profile
script.
To make the settings permanent for
all
accounts on your system, create a one-line
.sh
script in your system's
/etc/profile.d
folder and add the source command to the file.
For details about environment variables, see
Ubuntu documentation.
You can manage the
setvars.sh
script using a configuration file. This is helpful if you need to initialize specific versions of libraries or a compiler, rather than defaulting to the latest version. For details, see
Using a Configuration File to Manage Setvars.sh.
If you need to setup the environment in a non-POSIX shell, see
oneAPI Development Environment Setup for more configuration options.
Set up System to Analyze GPU
To work with GPU workloads, you need to configure your system properly.
Install GPU Drivers
To install GPU drives, follow the instructions for your system in the
Installation Guide.
Set up Permission
Non-root users typically do not have access to a GPU device to analyze GPU compute workloads. You need to add the non-root user(s) to a
video
group. Otherwise, binaries compiled for the GPU device will fail when executed by a non-root user.
You need root permissions to set up the permission.
To add the non-root user to the
video
group, run the following command:
sudo usermod -a -G video <username>
Disable Hangcheck
A workload that takes more than four seconds for GPU hardware to execute is a long-running workload. By default, individual threads that qualify as long-running workloads are considered hung and are terminated. To avoid this problem, disable the hangcheck timeout period.
Disable hangcheck
only
for applications with long-running GPU compute workloads in native environments.
You need root permissions.
To disable hangcheck, run the following:
sudo sh -c "echo N> /sys/module/i915/parameters/enable_hangcheck"
After you reboot your system, hangcheck is automatically enabled. You need to disable hangcheck again after every reboot or follow the instructions below to disable hangcheck permanently.
To disable hangcheck permanently:
- Open a new terminal.
- Navigate to the/etc/defaultdirectory and open thegrubfile for editing.
- In thegrubfile, find the lineGRUB_CMDLINE_LINUX_DEFAULT="".
- Between the quotes, type the following:i915.enable_hangcheck=0
- Run the following command:sudo update-grub
- Reboot the system. Hangcheck should remain disabled.
If you update the kernel, hangcheck is automatically enabled. Run the instructions above after every kernel update to ensure hangcheck is disabled.
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.
- 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 aX11: Failed to open displayerror.
- 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
- 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.
- Run a GUI application, such asxclock, to verify the container can run GUI applications. Xclock is available as one of the following:
- In thexorg-x11-appspackage on CentOS/Red Hat
- In thexclockpackage on SUSE
- On thex11-appson 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.
- InstallGrip* 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® oneAPI Rendering Toolkit
by
building and running sample applications.
Feedback
Share your feedback on this article in the
Intel® oneAPI Rendering Toolkit
forum.