Build Intel® oneAPI Rendering Toolkit (Beta) Libraries on Linux* OS

This article describes building Intel® oneAPI Rendering Toolkit (Render Kit) libraries from sources. Use this guide if you want 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 Render Kit libraries into your own production projects.
  • Integrate typical third-party imaging libraries and interactive windowing libraries.
  • Choose different tasking libraries and modules for desired functionality on different target application environments.

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 is not recommended for first-time users.

Prerequisites

Software prerequisites
  • CMake* 3.12 or higher
  • A C++11 compiler. For example: GNU Compiler Collection (GCC)*, Clang*, Intel® C++ Compiler 17.0 or higher
  • Python* 2.7 or higher
  • GLFW3*
  • Intel® Implicit SPMD Program Compiler (Intel® ISPC)
  • Intel® Threading Building Blocks (Intel® TBB)
Optional

The following prerequsites are requied for some ilibrary samples only:

  • X.org* runtimes and headers

NOTE: This xorg-dev package deploys the required libx11-6, libxrandr2, libxinerama1, libxxf86vm1, libxcursor1 libraries and accompanying development packages.

  • libGL*
  • OpenImageIO* libraries (libopenimageio, libopenimageio-dev)
  • Git* Large Files Storage (Git* LFS)
  • CMake* GUI (cmake-curses-gui)
  • ImageMagick*
Estimated time

Automatic build: 15 minutes

Manual build: 45-60 minutes

 

Library Source Locations

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

  • To build the Intel® oneAPI Rendering Toolkit using automated scripts:
  • To 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 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

Prerequiste: Set Up 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 Render Kit libraries, but it is highly recommended because some Render Kit samples use it to draw outputs in a GUI windows. 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

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. Save the file.

  5. Create a new directory to stage the build:

    mkdir build
    cd build

     

  6. Configure the component build:

    cmake .. -DCMAKE_BUILD_TYPE=Release

     

  7. Stage Intel TBB headers:

    # Copy the TBB include directory to the install directory. This example uses tbb-2020.3
    cp -r tbb-2020.3/unpacked/tbb/include install/ .
    

     

  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 compunent runtime and TBB 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:

    1. Intel OSPRay sample:

      ./ospExamples

       

    2. Intel Open VKL sample:

      ./vklExamples

       

    3. Intel Embree sample:

      ./embree3/triangle_geometry

       

  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 input.pfm
      convert -endian LSB mazda_firsthit_512spp_albedo.jpg albedo.pfm

       

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

      ./oidnDenoise -ldr input.pfm -alb albedo.pfm -o output.pfm

       

    4. Open the result images with ImageMagick:

      display output.pfm

       

Build the Libraries Manually

Building the libraries manually is recommended if you want to edit or add modules to one or more Render Kit libraries.

Set Up Dependencies

Configure 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 Render Kit is recommended because it can greatly improve performance.

To configure the Intel ISPC for the Render Kit:

  1. Download the Intel ISPC binary package from https://github.com/ispc/ispc/releases. NOTE: At time of publication, Intel ISPC 1.14.1 for Linux* OS is used.
  2. While in the rk directory, extract the binary in the current directory:

    tar -xvf ~/Downloads/ispc-v1.14.1-linux.tar.gz
  3. Add the Intel ISPC to the PATH environment variable so that component libraries can access it:

    export PATH=<path-to-ispc>/bin:${PATH}

     

Get Intel® Threading Building Blocks

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

NOTE: The Intel TBB version validated with the latest Render Kit is 2020.3.

  1. Download the Intel TBB.
  2. While in the rk directory, stage the Intel TBB prebuilt library and headers for development. It will be extracted to /home/${USER}/rk.
    tar -xvf /home/${USER}/Downloads/tbb-2020.3-lin.tgz 

     

Build the Libraries

Build rkcommon

rkcommon (formerly known as OSPCommon) is a support library used by the Render Kit components. It abstracts common math and vectorization operations, tasking implemented with Intel TBB, operating system input and output, networking, and memory capabilities to use in Render Kit components. rkcommon is not component specific. Intel OSPray and Intel Open VKL can automatically download and build rkcommon. However, when building more than one Render Kit library, you should build the rkcommon manually so that all components reference the same version of rkcommon.

NOTE: The latest Render Kit requires rkcommon (OSPCommon) 1.5.0.

While in the rk build directory:

  1. Get rkcommon (formerly known as OSPCommon) 1.5.0 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.5.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/tbb -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 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.12.0

     

  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/tbb -DCMAKE_INSTALL_PREFIX=../install -DCMAKE_PREFIX_PATH=/home/${USER}/rk/glfw/install
    cmake --build . -- -j4

    NOTE: The building might take up to 10 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 Intel TBB and Intel Embree runtime libraries:
    export LD_LIBRARY_PATH=../../lib:../../../../tbb/lib/intel64/gcc4.8
  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/v0.11.0

     

  3. Create a new directory to stage the build:

    mkdir build
    cd build
  4. Set up environment variables for the Intel TBB, rkcommon (formerly known as OSPCommon), Intel Embree, and GLFW libraries:

    export TBB_ROOT=/home/${USER}/rk/tbb
    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/tbb
  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=../lib:../../../rkcommon/install/lib:../../../tbb/lib/intel64/gcc4.8:../../../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 Intel TBB, rkcommon (formerly known as OSPCommon), 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=ON \
-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.2.4

       

    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/tbb -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/tbb -DCMAKE_INSTALL_PREFIX=../install

      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 <inputfile.jpg> -endian LSB -resize 1280x720 <outputfile.pfm> #ensure a consistent size for both noisy input and albedo inputs with -resize.

     

  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=../lib/ 
  6. Run the oidnDenoise sample application:
    ./oidnDenoise -ldr <your_noisy_input_file>.pfm -alb <your_albedo_file>.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. Use the system package manager to install OpenImageIO.

Build Intel® OSPRay

NOTE: Intel OSPRay requires other Render Kit 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 https://github.com/ospray/ospray.git ospray
    cd ospray
    git fetch --tag
    git checkout tags/v2.4.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/tbb
    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
    #For OpenImageDenoise support in ospExamples:
    export OpenImageDenoise_DIR=/home/${USER}/rk/oidn/install
    
  5. Configure the build:

    cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install -DOSPRAY_MODULE_DENOISER=ON
  6. 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=../lib:../../../rkcommon/install/lib:../../../tbb/lib/intel64/gcc4.8:../../../embree/install/lib:../../../openvkl/install/lib:../../../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.

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.

Sample Error: Invalid tensor format

If you run the Intel Open Image Denoise oidnDenoise sample, you may see the ‘invalid tensor format’ error in the terminal. The program fails.

The OSPRay example viewer may stop operating when OIDN is enabled for real-time denoising. The GUI and application may become unresponsive.

Solution: Ensure Intel Open Image Denoise has appropriately acquired the denoising weights. The Intel Open Image Denoise repository requires git-lfs when acquiring weights from the repository. Placeholder files may be pulled down in place of Intel Open Image Denoise weights. This can cause an error.

Intel® oneAPI Rendering Toolkit Libraries Superbuild

Intel OSPRay, Intel OpenVKL and other libraries may be buildable with a ‘superbuild’ CMakeLists.txt, which downloads and builds prerequisite components. If you would like to build libraries and samples only for a specific component, this is a recommended build method. Please configure your CMake build with the CMakeLists.txt files in the superbuild subdirectory.

Performance Considerations

Render Kit 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® AVX512) hardware. Consider using Intel® AVX512-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.

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.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804