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:

  • Explore sample programs in depth.
  • Perform minor edits and rebuild sample programs to understand API usage.
  • Quickly integrate Render Kit libraries with your own production projects.
  • Integrate typical third-party imaging libraries and interactive windowing libraries.
  • Explore typical requirements for your application input and output.
  • Choose different tasking libraries and modules for desired functionality on different target application environments.
  • Understand where to take optimized library reference sources and use it for your own programs.

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.1 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
Optional
  • 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* with git-lfs
  • CMake* GUI
  • ImageMaigck*
Estimated time 45-60 minutes

Library Source Locations

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

  • Download the Intel® oneAPI Rendering Toolkit distribution:
  • 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 will provide instructions for both options.

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-beta06-build --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

xclock should open in a new GUI window. If it does not appear, check your Docker 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 oneapi_renderkit_src folder in a /home/${USER} directory:

mkdir oneapi_renderkit_src
cd /home/${USER}/oneapi_renderkit_src

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.12b for Linux* OS was used.Intel ISPC 1.13 might show errors when used to build components.
  2. While in the oneapi_renderkit_src directory, extract the binary in the current directory:

    tar -xvf ~/Downloads/ispc-v1.12.0b-linux.tar.gz

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.1.

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

Build rkcommon Library

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.3.0.

While in the oneapi_renderkit_src build directory:

  1. Get rkcommon (formerly known as OSPCommon) 1.3.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.3.0

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

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

Build 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 Render Kit libraries, but it is highly recommended because some Intel oneAPI Rendering Toolkit samples use it to draw outputs to GUI windows. If you target a headless environment, you may still want to explore the GUI samples as they demonstrate key library API features.

NOTE: You can install GLFW3 from your system package manager repositories instead of building it manually. This may be preferred in particular for end-user deployment evaluation. For example, to install it on Ubuntu OS, run: apt install libglfw3 libglfw3-dev

To build the GLFW library:

  1. Go to the build oneapi_renderkit_src directory:
    cd /home/${USER}/oneapi_renderkit_src
  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 Intel oneAPI Rendering Toolkit 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}/oneapi_renderkit_src/
  2. Get the Intel Embree sources. Choose one of the following options:

    • Stage sources from the installed Render Kit distribution: Copy the sources from <install-dir>/embree/latest/src into the build directory oneapi_renderkit_src:

      cp -r <install-dir>/embree/latest/src/embree .
      cd embree

    • Get sources a from Git* repository:

      git clone --no-checkout https://github.com/embree/embree.git embree
      cd embree
      git fetch --tag
      git checkout tags/v3.9.0
  3. Create a new directory to stage the build:

    mkdir build
    cd build
  4. Build the Intel Embree:

    cmake .. -DEMBREE_TBB_ROOT=/home/${USER}/oneapi_renderkit_src/tbb -DCMAKE_INSTALL_PREFIX=../install -DCMAKE_PREFIX_PATH=/home/${USER}/oneapi_renderkit_src/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}/oneapi_renderkit_src/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 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}/oneapi_renderkit_src/
  2. Get the Intel Open VKL sources. Choose one of the following options:

    • Stage sources from the installed Render Kit distribution: Copy the sources from <install-dir>/openvkl/latest/src into the build directory oneapi_renderkit_src:

      cp -r <install-dir>/openvkl/latest/src/openvkl .
      cd openvkl

    • Get sources a from Git* repository:

      git clone https://github.com/openvkl/openvkl.git openvkl
      cd openvkl
      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 the Intel TBB, rkcommon (formerly known as OSPCommon), Intel Embree, and GLFW libraries:

    export OSPCOMMON_TBB_ROOT=/home/${USER}/oneapi_renderkit_src/tbb
    export ospcommon_DIR=/home/${USER}/oneapi_renderkit_src/ospcommon/install
    export embree_DIR=/home/${USER}/oneapi_renderkit_src/embree/install
    export glfw3_DIR=/home/${USER}/oneapi_renderkit_src/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}/oneapi_renderkit_src/openvkl/install ..
  6. Build and install Intel Open VKL:

    cmake --build . -- -j4
    make install

Errata: Intel Open VKL testing and benchmark was not implemented in the superbuild as of Render Kit Beta06.

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

  1. Go to bin directory with samples:
    cd /home/${USER}/oneapi_renderkit_src/openvkl/install/bin
  2. Set library path to enable dynamic search for component runtime libraries:
    export LD_LIBRARY_PATH=../lib:../../../ospcommon/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 uses 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=OFF \
-DBUILD_OPENVKL_BENCHMARKS=OFF \
-DBUILD_OPENVKL_TESTING=OFF \
-DBUILD_OSPCOMMON=OFF \
-DBUILD_TBB=OFF "

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

Build Intel® Open Image Denoise

  1. Go to the build directory:
    cd /home/${USER}/oneapi_renderkit_src/
  2. Get the Intel Open Image Denoise sources. Choose one of the following options:

    • Stage sources from the installed Render Kit distribution: Copy the sources from <install-dir>/oidn/latest/src into the build directory oneapi_renderkit_src:

      cp -r <install-dir>/oidn/latest/src/oidn .
      
      cd oidn

    • Get sources a from Git* repository:

      1. Clone the Intel Open Image Denoise sources:

        git clone --recursive https://github.com/OpenImageDenoise/oidn.git oidn
        cd oidn
        git fetch --tag
        git checkout tags/v1.2.0
      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}/oneapi_renderkit_src/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}/oneapi_renderkit_src/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}/oneapi_renderkit_src/oidn/install/bin
  5. Set library path to enable dynamic search for component runtime libraries:
    export LD_LIBRARY_PATH=../lib/ 
  6. Run the denoise sample application:
    ./denoise -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. It is recommended to use the system package manager to install OpenImageIO as opposed to building it.

Build Intel® OSPRay

NOTE: Intel OSPRay requires other Render Kit libraries to be installed.

  1. Go to the build directory:
    cd /home/${USER}/oneapi_renderkit_src/
  2. Get the Intel Open VKL sources. Choose one of the following options:

    • Stage sources from the installed Render Kit distribution: Copy the sources from <install-dir>/ospray/latest/src into the build directory oneapi_renderkit_src:

      cp -r <install-dir>/ospray/latest/src/ospray .
      cd ospray

    • Get sources a from Git* repository:

      git clone https://github.com/ospray/ospray.git ospray
      cd ospray
      git fetch --tag
      git checkout tags/v2.1.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 OSPCOMMON_TBB_ROOT=/home/${USER}/oneapi_renderkit_src/tbb
    export ospcommon_DIR=/home/${USER}/oneapi_renderkit_src/ospcommon/install
    export embree_DIR=/home/${USER}/oneapi_renderkit_src/embree/install
    export glfw3_DIR=/home/${USER}/oneapi_renderkit_src/glfw/install
    export openvkl_DIR=/home/${USER}/oneapi_renderkit_src/openvkl/install
    #For OpenImageDenoise support in ospExamples:
    export OpenImageDenoise_DIR=/home/${USER}/oneapi_renderkit_src/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}/oneapi_renderkit_src/ospray/install/bin
  2. Set library path to enable dynamic search for component runtime:
    export LD_LIBRARY_PATH=../lib:../../../ospcommon/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

Explore the ospExamples viewer:

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 denoise 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.

Информация о продукте и производительности

1

Компиляторы Intel могут не обеспечивать для процессоров других производителей уровень оптимизации, который не является присущим только процессорам Intel. В состав этих оптимизаций входят наборы команд SSE2, SSE3 и SSSE3, а также другие оптимизации. Корпорация Intel не гарантирует доступность, функциональность или эффективность работы любых приложений оптимизации для микропроцессоров других производителей. Содержащиеся в данной продукции оптимизации, предназначены для использования с конкретными микропроцессорами Intel. Некоторые оптимизации, не относящиеся к микроархитектуре Intel, зарезервированы для микропроцессоров Intel. Пожалуйста, см. соответствующее руководство пользователя или справочные руководства для получения дополнительной информации о конкретных наборах команд, к которым относится данное уведомление.

Редакция уведомления № 20110804