Build Intel® oneAPI Rendering Toolkit Libraries on Linux* OS

This article describes building Intel® oneAPI Rendering Toolkit (Render Kit) components from sources. Use this guide to:

• Review sample programs in depth and edit them to understand API usage.
• Get critical performance optimizations of core library performance by way of Intel® Implicit SPMD Program Compiled (Intel® ISPC).
• Quickly integrate Intel oneAPI Rendering Toolkit libraries into your own production projects.
• Integrate typical third-party imaging libraries and interactive windowing libraries.

NOTE: This walkthrough explains how to build components so that source and executables are staged for a non-administrator system user. Administrator prerequisites are minimal for this guide.

IMPORTANT: Skipping sections of this document, including optional, is not recommended for first-time users.

Prerequisites

Library Source Locations

You can use one of the following ways to get the source code:

• Build the Intel® oneAPI Rendering Toolkit using automated scripts:
  • Download the Intel® oneAPI Rendering Toolkit distribution:
    • From the Intel oneAPI Rendering Toolkit product page as a full-package local installer or online installer. For more information, see Installation Guide for Intel® oneAPI Toolkits.
    • From Intel® Linux* package manager repositories. For more information, see Installing Intel® oneAPI Toolkits via Linux* Package Managers.
  • After you download and install the Intel oneAPI Rendering Toolkit, you can get the component sources using a CMake script located at <install-dir>/rkutil. By default, <install-dir> is /opt/intel/oneapi.
• Build the Intel® oneAPI Rendering Toolkit manually:
  • Check out sources for each component separately from corresponding GitHub* portals.
  • If you choose this option, make sure to check out components versioned for the same oneAPI release as they are validated together. See the Release Notes pages for the toolkit component version manifests. Use the tags listed in the GitHub repositories to check out the corresponding component versions.

The component sections below provide instructions for both automatic and manual building options. Both instructions use Intel ISPC, which improves and optimizes core library performance.

Optional: Configure a Docker* Container

If you want to build the libraries in a Docker* container:

1. Enable drawing in a graphical user interface (GUI) within the Docker container:

   xhost +

    

2. Run the Docker container with the DISPLAY variable and a volume -v reference for X11 to allow for drawing to GUI. For example, for Ubuntu* OS 20.04, use the command below. NOTE: If you have proxy set up on your system, add corresponding proxy environment variables to the command below.

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

    

3. While in the container, install the X.Org package. For example, on Ubuntu OS:

   apt update

   apt install x11-apps

    

After you run the xclock command, its output opens in a new GUI window. If it does not appear, check your Docker and X Windows forwarding configuration.

Stage a Build Directory

After you install the Intel oneAPI Rendering Toolkit package on your system or in a Docker container, create a new directory for library sources at a writable location.

NOTE: If you want to work in a container, run all the commands below while you are in the container.

For example, create a rk folder in a /home/${USER} directory:

mkdir rk

cd /home/${USER}/rk

Build the Libraries Automatically

1. Go to the build rk directory:

   cd /home/${USER}/rk

    

2. Get the rkUtil files.
   • From GitHub*repository:

     git clone https://github.com/RenderKit/superbuild .

      

   • From the installed distribution:

     cp -r <rendering-toolkit-install-dir>/rkutil/* .

      

3. Turn on sample building. Open a CMakeLists.txt for editing in a preferred text editor and enable one or more of the toggles below for component samples you want to build:

   …
   -DEMBREE_TUTORIALS=ON
   …
   -DBUILD_EXAMPLES=ON
   …
   -DOIDN_APPS=ON
   …
   -DOSPRAY_ENABLE_APPS=ON

    

4. Optional: Turn on OpenImageIO for extended texture support for Intel® OSPRay Studio. In the CMakeLists.txt file, set the following option to ON:

   -DENABLE_OPENIMAGEIO=ON

    

5. Save the file.

6. Create a new directory to stage the build:

   mkdir build

   cd build

    

7. Configure the component build:

   cmake .. -DCMAKE_BUILD_TYPE=Release

    

8. Build the components with the headers:

   cmake --build .

    

9. Navigate to the default install directory with the CMake script:

   cd install/bin

    

10. Configure the dynamic search path and check that it includes the component runtime and oneTBB runtime paths:

    export LD_LIBRARY_PATH=$(readlink -f ../lib):$(readlink -f ../lib/intel64/gcc.4.8):${LD_LIBRARY_PATH}
    echo $LD_LIBRARY_PATH

     

11. Check the interactive GUI sample programs:

    • Intel OSPRay sample:

      ./ospExamples

       

    • Intel Open VKL sample:

      ./vklExamples

       

    • Intel Embree sample:

      ./embree3/triangle_geometry

       

    • Intel OSPRay Studio application:

      ./ospStudio

       

12. Check the Intel Open Image Denoise sample:

    1. Download test images for Intel Open Image Denoise:

       wget https://openimagedenoise.github.io/images/mazda_64spp_input.jpg

       wget https://openimagedenoise.github.io/images/mazda_firsthit_512spp_albedo.jpg

        

    2. Convert the images to the Intel Open Image Denoise-friendly format with ImageMagick:

       convert -resize 1280x720 -endian LSB mazda_64spp_input.jpg mazda_64spp_input.pfm

       convert -endian LSB mazda_firsthit_512spp_albedo.jpg mazda_firsthit_512spp_albedo.pfm

        

    3. Denoise the test images with the Intel Open Image Denoise sample: 

       ./oidnDenoise -ldr mazda_64spp_input.pfm -alb mazda_firsthit_512spp_albedo.pfm -o denoise.pfm

        

    4. Open the result images with ImageMagick:

       display denoise.pfm

        

Build the Libraries Manually

Building the libraries manually is recommended if you want to edit or add modules to one or more Intel oneAPI Rendering Toolkit libraries.

Set Up Dependencies

Configure the Intel® Implicit SPMD Program Compiler

Intel® Implicit SPMD Program Compiler (Intel® ISPC) is a compiler tuned for wide vector instructions available on Intel® architectures. Using the Intel ISPC with the Intel oneAPI Rendering Toolkit is recommended because it can greatly improve performance.

To configure the Intel ISPC for the Intel oneAPI Rendering Toolkit:

1. Download the Intel ISPC binary package from https://github.com/ispc/ispc/releases. NOTE: The article uses Intel ISPC 1.15.0.

2. While in the rk directory, extract the binary in the current directory:

   tar -xvf ~/Downloads/ispc-v1.15.0-linux.tar.gz

NOTE: Intel oneAPI Rendering Toolkit programs accelerated with еру Intel ISPC are expected to achieve better performance through Intel® Advanced Vector Extensions 2 (Intel® AVX2) and even more so for subsequent Intel® Advanced Vector Extensions 512 (Intel® AVX-512) hardware. Consider using Intel® AVX-512 capable hardware (Intel® microarchitecture code name Skylake) for new hardware deployments. Run cat /proc/cpuinfo for Linux* OS to see available instruction set extensions on your target hardware. Review technical features for Intel® processors at http://ark.intel.com.

Build the GLFW3* Library

GLFW3* is used as an interfacing layer for OpenGL*-based drawing for reference applications. This article uses GLFW 3.3.2.

GLFW3 is not required for the Intel oneAPI Rendering Toolkit libraries, but it is highly recommended because some Intel oneAPI Rendering Toolkit samples use it to draw outputs in a GUI window. If you target a headless environment, you may still want to explore the GUI samples as they demonstrate key library API features.

Do one of the following:

• Install GLFW3 from your system package manager repository automatically. This option is particularly recommended for end-user deployment evaluation. For example, to install it on Ubuntu OS, run: 

  apt install libglfw3 libglfw3-dev

   

• Manually build the GLFW library:
  1. Go to the build rk directory:

     cd /home/${USER}/rk

  2. Get GLFW3 sources from the Git* repository:

     git clone --no-checkout https://github.com/glfw/glfw.git glfw

     cd glfw

     git fetch --tags

     git checkout tags/3.3.2

  3. Create a new directory to stage the GLFW build:

     mkdir build

     cd build

      

  4. Build GLFW:

     cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install

     cmake --build . -- -j4

     cmake --build . --target install

If you build the GLFW library manually, it will be linked dynamically. If you use the automatic rkUtil superbuild, the CMake script links a static GLFW library.

Get thte Intel® oneAPI Threading Building Blocks

Intel® oneAPI Threading Building Blocks (oneTBB) is used for tasking within the infrastructure for Intel oneAPI Rendering Toolkit libraries. oneTBB is recommended to use for building Intel oneAPI Rendering Toolkit libraries, but there are other build-time configurable options, for example, OpenMP*.

IMPORTANT: Use the same oneTBB library version for all Intel oneAPI Rendering Toolkit components. Recommended version is oneTBB 2021.1 or higher. This guide uses Intel oneAPI Rendering Toolkit with oneTBB 2021.2.0.

1. Download the oneTBB.
2. While in the rk directory, stage the oneTBB prebuilt library and headers for development. It will be extracted to /home/${USER}/rk.

   tar -xvf /home/${USER}/Downloads/oneapi-tbb-2021.2.0-lin.tgz

    

Build rkcommon

rkcommon is a support library used by the Intel oneAPI Rendering Toolkit components. It abstracts common math and vectorization operations, tasking implemented with oneTBB, operating system input and output, networking, and memory capabilities to use in the Intel oneAPI Rendering Toolkit components. Intel OSPRay and Intel Open VKL can automatically download and build rkcommon. However, when building more than one Intel oneAPI Rendering Toolkit library, you should build the rkcommon manually so that all components reference the same version of rkcommon.

NOTE: The latest Intel oneAPI Rendering Toolkit requires rkcommon 1.8.0.

While in the rk build directory:

1. Get rkcommon 1.6.1 sources from the Git* repository:

   git clone --no-checkout https://github.com/ospray/rkcommon.git rkcommon

   cd rkcommon 

   git fetch --tags

   git checkout tags/v1.8.0

    

2. Create a new directory to stage the rkcommon build:

   mkdir build

   cd build

3. Configure, build, and install rkcommon:

   cmake .. -DCMAKE_BUILD_TYPE=Release -DTBB_ROOT=/home/${USER}/rk/oneapi-tbb-2021.2.0 -DCMAKE_INSTALL_PREFIX=../install

   cmake --build . -- -j4

   make install

    

Deployed bin, include, and lib directories contain a test executable, headers, libraries, and CMake references.

Build the Libraries

Build Intel® Embree

NOTE: The Intel Embree build uses the Intel ISPC compiler as added to the PATH variable earlier in this document.

1. Go to the build directory:

   cd /home/${USER}/rk/

    

2. Get the Intel Embree sources from a Git* repository:

   git clone --no-checkout https://github.com/embree/embree.git embree

   cd embree

   git fetch --tags

   git checkout tags/v3.13.2

    

3. Create a new directory to stage the build:

   mkdir build

   cd build

    

4. Build Intel Embree:

   cmake .. -DCMAKE_BUILD_TYPE=Release -DEMBREE_TBB_ROOT=/home/${USER}/rk/oneapi-tbb-2021.2.0 -DCMAKE_INSTALL_PREFIX=../install -DCMAKE_PREFIX_PATH=/home/${USER}/rk/glfw/install

   cmake --build . -- -j4

   NOTE: The building might take up to 15 minutes. Increase the value for -j<num> for a quicker build.

5. Install the build:

   make install

    

To verify your Intel Embree build and installation, you can run a sample:

1. Go to sample directory:

   cd /home/${USER}/rk/embree/install/bin/embree3

2. Set library path to see the oneTBB and Intel Embree runtime libraries:

   export LD_LIBRARY_PATH=$(readlink -f ../../lib):$(readlink -f ../../../../oneapi-tbb-2021.2.0/lib/intel64/gcc4.8)

   echo $LD_LIBRARY_PATH

3. Run the interactive triangle geometry sample:

   ./triangle_geometry

    

Successful launch displays an interactive window rendering a cube. If the cube does not appear within a GUI window, please check your GUI and runtime configuration.

Build Intel® Open Volume Kernel Library

1. Go to the build directory:

   cd /home/${USER}/rk/

2. Get the Intel Open VKL sources from a Git repository:

   git clone https://github.com/openvkl/openvkl.git openvkl

   cd openvkl

   git fetch --tag

   git checkout tags/v1.1.0

    

3. Create a new directory to stage the build:

   mkdir build

   cd build

4. Set up environment variables for the oneTBB, rkcommon, Intel Embree, and GLFW libraries:

   export TBB_ROOT=/home/${USER}/rk/oneapi-tbb-2021.2.0

   export rkcommon_DIR=/home/${USER}/rk/rkcommon/install

   export embree_DIR=/home/${USER}/rk/embree/install

   export glfw3_DIR=/home/${USER}/rk/glfw/install

5. Configure Intel OpenVKL to use the library versions that you have built:

   cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/home/${USER}/rk/openvkl/install -DTBB_ROOT=/home/{USER}/rk/oneapi-tbb-2021.2.0

6. Build and install Intel Open VKL:

   cmake --build . -- -j4
   make install

    

To verify your Intel Open VKL build and installation, you can run a sample:

1. Go to bin directory with samples:

   cd /home/${USER}/rk/openvkl/install/bin

2. Set library path to enable dynamic search for component runtime libraries:

   export LD_LIBRARY_PATH=$(readlink -f ../lib):$(readlink -f ../../../rkcommon/install/lib):$(readlink -f ../../../oneapi-tbb-2021.2.0/lib/intel64/gcc4.8):$(readlink -f ../../../embree/install/lib)

3. Run Intel Open VKL samples:

   • Hello-world vklTutorial sample:

     ./vklTutorial

     You should see the application output printed to the command prompt.

   • Hello-world vklTutorialISPC sample with Intel ISPC acceleration:

     ./vklTutorialISPC

     You should see the application output printed to the command prompt.

   • vklExample sample, which renders results to screen through a graphical interface:

     ./vklExamples

     You should see the application output in a new GUI window.

NOTE: Intel Open VKL has a CMakeLists.txt file implementing a ‘superbuild’ from its superbuild directory. The superbuild can automatically download and install validated versions of Intel Open VKL dependencies, such as oneTBB, rkcommon, GLFW3, Intel Embree, OpenVDB*. If your work is limited to Intel Open VKL only, consider using the superbuild for Intel Open VKL. Configuration toggles can be set after CMake configuration:

export SUPERBUILD_CONTROL="-DBUILD_BLOSC=OFF \
-DBUILD_DEPENDENCIES_ONLY=OFF \
-DBUILD_EMBREE=OFF \
-DBUILD_EMBREE_FROM_SOURCE=OFF \
-DBUILD_GLFW=OFF \
-DBUILD_ISPC=OFF \
-DBUILD_JOBS=4 \
-DBUILD_OPENVDB=OFF \
-DBUILD_OPENVKL_BENCHMARKS=OFF \
-DBUILD_OPENVKL_TESTING=OFF \
-DBUILD_RKCOMMON=OFF \
-DBUILD_TBB=OFF "

cmake ../superbuild ${SUPERBUILD_CONTROL}  -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/home/${USER}/rk/openvkl/install

Build Intel® Open Image Denoise

1. Go to the build directory:

   cd /home/${USER}/rk/

2. Get the Intel Open Image Denoise sources from a Git repository:

   1. Clone the Intel Open Image Denoise sources:

      git clone --recursive https://github.com/OpenImageDenoise/oidn.git oidn

      cd oidn

      git fetch --tags

      git checkout tags/v1.4.2

       

   2. Update the mkl-dnn and the weights submodules:

      git submodule update --init --recursive

       

3. Create a new build directory:

   mkdir build

   cd build

4. Configure the build:

   • If you have libopenimageio, configure the build with libopenimageio enabled for Intel Open Image Denoise sample applications:

     cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/home/${USER}/rk/oneapi-tbb-2021.2.0 -DCMAKE_INSTALL_PREFIX=../install -DOIDN_APPS=ON -DOIDN_APPS_OPENIMAGEIO=ON

      

   • If you do not have libopenimageio:

     cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/home/${USER}/rk/oneapi-tbb-2021.2.0 -DCMAKE_INSTALL_PREFIX=../install -DOIDN_APPS=ON -DOIDN_APPS_OPENIMAGEIO=OFF

     NOTE: CMake may report OpenImageIO warnings, but the build should continue.

5. Build the Intel Open Image Denoise:

   cmake --build . -- -j4

   make install

    

To verify your Intel Open Image Denoise build and installation, run a sample:

1. Download an example noisy input file: https://openimagedenoise.github.io/images/mazda_64spp_input.jpg
2. Download the corresponding albedo file: https://openimagedenoise.github.io/images/mazda_firsthit_512spp_albedo.jpg
3. Convert both images to pfm format with ImageMagick:

   convert mazda_64spp_input.jpg -endian LSB -resize 1280x720 mazda_64spp_input.pfm

   convert mazda_firsthit_512spp_albedo.jpg -endian LSB -resize 1280x720 mazda_firsthit_512spp_albedo.pfm

   NOTE: Use the -resize to make sure the noisy and albedo input images are of the same size.

4. Go to bin directory with samples:

   cd /home/${USER}/rk/oidn/install/bin

5. Set library path to enable dynamic search for component runtime libraries:

   export LD_LIBRARY_PATH=$(readlink -f ../lib):$(readlink -f ../../../oneapi-tbb-2021.2.0/lib/intel64/gcc4.8)

6. Run the oidnDenoise sample application:

   ./oidnDenoise -ldr mazda_64spp_input.pfm -alb mazda_firsthit_512spp_albedo.pfm -o denoise.pfm

NOTE: You can use the OpenImageIO library to load and unload images for Intel Open Image Denoise samples, but it is not required. OpenImageIO dependencies include many imaging and productivity libraries common to other applications. Recommendation: Use the system package manager to install OpenImageIO.

Build Intel® OSPRay

NOTE: Intel OSPRay requires other Intel oneAPI Rendering Toolkit libraries to be installed.

1. Go to the build directory:

   cd /home/${USER}/rk/

2. Get the Intel OSPRay sources from a Git repository:

   git clone --no-checkout https://github.com/ospray/ospray.git ospray

   cd ospray

   git fetch --tag

   git checkout tags/v2.8.0

    

3. Create a new directory to stage the build:

   mkdir build

   cd build

4. Set up environment variables for library build-time dependencies:

   export TBB_ROOT=/home/${USER}/rk/oneapi-tbb-2021.2.0

   export rkcommon_DIR=/home/${USER}/rk/rkcommon/install

   export embree_DIR=/home/${USER}/rk/embree/install

   export glfw3_DIR=/home/${USER}/rk/glfw/install

   export openvkl_DIR=/home/${USER}/rk/openvkl/install

    

5. Enable Intel Open Image Denoise support for ospExamples:

   export OpenImageDenoise_DIR=/home/${USER}/rk/oidn/install
   

6. Configure the build:

   cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install -DOSPRAY_MODULE_DENOISER=ON

7. Build and install the Intel OSPRay:

   cmake --build . -- -j4

   make install

    

To verify your Intel OSPRay build and installation, run the samples:

1. Go to bin directory with samples:

   cd /home/${USER}/rk/ospray/install/bin

2. Set library path to enable dynamic search for component runtime:

   export LD_LIBRARY_PATH=$(readlink -f ../lib):$(readlink -f ../../../rkcommon/install/lib):$(readlink -f ../../../oneapi-tbb-2021.2.0/lib/intel64/gcc4.8):$(readlink -f ../../../embree/install/lib):$(readlink -f ../../../openvkl/install/lib):$(readlink -f ../../../oidn/install/lib)

3. Run the ospTutorial Hello-World sample. This sample does not interface with the GUI environment:

   ./ospTutorial

4. Review the generated .ppm files with your preferred image viewer. For example, to open the images in theFor example, to open the images in the ImageMagick:

   ls *.ppm

   display accumulatedFrame.ppm #imagick display
   

   display firstFrame.ppm #imagick display

    

Run the ospExamples viewer:

./ospExamples

You get the interactive output:

​

ospExamples combines much of the functionality of Intel oneAPI Rendering Toolkit libraries into an interactive reference program.

• Switch between typical geometries using the Scene drop-down.
• Switch between pathtracer and scivis renderers using the Renderer drop down.
• Control the virtual camera position by clicking and holding left, middle, or right mouse button and moving the mouse.

The ospExamples reference program source is a great starting point for reviewing how scene geometry passes through Intel OSPRay and ultimately back to the interactive window.

Build Intel® OSPRay Studio

NOTE: Intel® OSPRay Studio requires Intel OSPRay.

1. Go to the build directory:

   cd /home/${USER}/rk/

    

2. Get the Intel OSPRay sources from a Git repository:

   git clone --no-checkout https://github.com/ospray/ospray_studio.git ospray_studio

   cd ospray_studio

   git fetch --tag

   git checkout tags/v0.9.0

    

3. Create a new directory to stage the build:

   mkdir build

   cd build

    

4. Set up environment variables for library build-time dependencies:

   export TBB_ROOT=/home/${USER}/rk/oneapi-tbb-2021.2.0

   export rkcommon_DIR=/home/${USER}/rk/rkcommon/install

   export embree_DIR=/home/${USER}/rk/embree/install

   export glfw3_DIR=/home/${USER}/rk/glfw/install

   export openvkl_DIR=/home/${USER}/rk/openvkl/install

    

5. Optional: Enable Intel Open Image Denoise support in Intel OSPRay samples:

   export OpenImageDenoise_DIR=/home/${USER}/rk/oidn/install

   export ospray_DIR=/home/${USER}/rk/ospray/install

    

6. Configure the build:

   cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install

    

7. Build and install the Intel OSPRay:

   cmake --build . -- -j4

   make install

    

To verify your Intel OSPRay build and installation, run the samples:

1. Go to the bin directory with samples:

   cd /home/${USER}/rk/ospray_studio/install/bin

    

2. Set library path to enable dynamic search for component runtime:

   export LD_LIBRARY_PATH=$(readlink -f ../lib):$(readlink -f ../../../rkcommon/install/lib):$(readlink -f ../../../oneapi-tbb-2021.2.0/lib/intel64/gcc4.8):$(readlink -f ../../../embree/install/lib):$(readlink -f ../../../openvkl/install/lib):$(readlink -f ../../../oidn/install/lib):$(readlink -f ../../../ospray/install/lib)

    

3. Run the ospStudio:

   ./ospStudio

Troubleshooting

If you have deployment concerns or suggestions, please address the Intel Rendering Toolkit forum. Please let us know of any experience gaps.

For an out-of-box build and run perspective, see the Intel oneAPI Rendering Toolkit Get Started Guide for instructions on running and building the basic programs.

Notices and Disclaimers

Intel technologies may require enabled hardware, software or service activation.
No product or component can be absolutely secure.
Your costs and results may vary.
© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.
The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade.