Get Started

  • 2021.2
  • 03/26/2021
  • Public Content

Configure Your System

Intel® oneAPI Rendering Toolkit
If you use the
Intel® oneAPI Rendering Toolkit
(Render Kit) from the Intel® DevCloud, you can skip the prerequisite and configuration sections and start with running a sample application. Intel® DevCloud already has all the
Intel® oneAPI Rendering Toolkit
components installed. See Get Started with Intel DevCloud for oneAPI for details.
To set up your system, you need to:
Install the software prerequisites and the
Intel® oneAPI Rendering Toolkit
to the default installation directories. Otherwise, you might get an error.

Install Software Prerequisites

Open a new terminal session and run the following commands:
  1. For corporate network users: Ensure package management tools (for example, apt) can connect through your proxy servers if necessary. Set the following variables to configure your proxy:
    export http_proxy=http://<user>:<pass>@proxy.<server>.com:<port>
    export https_proxy=https://<user>:<pass>@proxy.<server>.com:<port>
    export HTTP_PROXY=${http_proxy}
    export HTTPS_PROXY=${https_proxy}
  2. Install dependencies for building applications and running sample applications:
    Intel® oneAPI Rendering Toolkit
    -based applications do not necessarily need to incorporate GUI elements. However, some of samples that best demonstrate
    Intel® oneAPI Rendering Toolkit
    features are GUI applications. Tools are listed with versions used in parentheses.
    Global prerequisites:
    • Install MacPorts* following the instructions on the MacPorts website.
      MacPorts is used to set up both developer and runtime prerequisites. You can also use Homebrew* to acquiring the requirements, but it is not tested.
    • Install Xcode* and Xcode command-line tools.
      1. Download and install the Xcode from the Apple* website or visit the App Store* from the Spotlight* tool.
      2. After you install the Xcode, run the following command to install Xcode command-line tools:
        xcode-select --install
      The Xcode tools offer default compilers, headers, and runtimes to compile by, link, and create Render Kit-based applications. These tools can also build the Render Kit libraries. You can also use other C99/C++11 compilers, for example, the
      Intel® oneAPI
      DPC++/C++
      Compiler
      , which links with Xcode provided libraries.
    • Install Git* with Git* Large File Storage (LFS). Do one of the following:
      • Download and install the Git LFS from the https://git-lfs.github.com/.
      • From MacPorts, run the following:
        sudo port install git
        sudo port install git-lfs
        git lfs install
      Git LFS is specifically needed when obtaining pre-trained neural network files for Intel® Open Image Denoise from Git repositories.
    • Install CMake* with
      ccmake
      .
      Do one of the following:
      • Download and install the CMake from the https://cmake.org/download/.
      • From MacPorts, run the following:
        sudo port install cmake
        MacPorts CMake package already includes
        ccmake
        .
      CMake is used to build sample programs and Render Kit libraries.
      ccmake
      is currently included with the MacPorts distribution and can be used to reconfigure and inspect build time parameters for Render Kit-based programs and the Render Kit libraries. Tunable parameter examples include but are not limited to: MPI-distributed computing support, Intel Open Image Denoise enabling modules for Intel® OSPRay-based programs, and the usage of extended imaging libraries in available sample programs.
    • Download and install the
      Intel® oneAPI Threading Building Blocks
      (
      oneTBB
      ) from a GitHub* repository.
      oneTBB
      is used as a tasking system amongst many Render Kit programs and libraries. Keep
      oneTBB
      version used consistent amongst all components used to build a program. Some programs and their prerequisite libraries depend on
      oneTBB
      .
    GUI and Imaging Requirements:
    These requirements are
    optional
    for deploying Render Kit-based programs, however, for evaluation and typical programs they are recommended.
    • Install XQuartz* (X11* server).
      1. Download and install XQuartz from the XQuartz website or run the following command from MacPorts:
        sudo port install xorg-server
      2. Enter
        x11
        from the Spotlight tool to launch the server.
      3. To test
        x11
        after launching it, install and run
        xclock
        :
        sudo port install xclock
        xclock
        Typically, the DISPLAY is available at
        :0
        . Change this value based on your configuration:
        export DISPLAY=<value>
      The XQuartz server allows running sample programs to launch GUI windows. Consider installing it and launching it
      before
      launching GUI-based programs.
    • Install GLFW*:
      sudo port install glfw
      GLFW is an interfacing library for OpenGL*. The most feature-rich Intel OSPRay sample programs use GLFW. The GLFW GUI-based sample programs are important for an introduction to Render Kit.
    • Install OpenImageIO*:
      sudo port install openimageio
      Typical deployment should be via system package manager like MacPorts as opposed to building it. OpenImageIO pulls in many other prerequisites that are very challenging to deploy by hand. Open Image IO libraries are used within some sample programs to render scenes using high dynamic range texture data.
    • Install ImageMagick*:
      sudo port install imagemagick
      ImageMagick is a suite of imaging conversion, parsing, and management tools. Use this to display, convert and stage input images from the command prompt.
    • Install
      libpng
      and
      libjpeg
      libraries:
      sudo port install libpng
      sudo port install jpeg
      Some sample programs have input/output functionality that can actuate on compressed image formats. Render Kit focuses on accelerated rendering algorithms, however, typical programs use the PNG or JPEG image file types. Some sample programs have operation modes that use these formats. These libraries are optional for evaluating Render Kit applications.

Intel® Implicit SPMD Program Compiler

Intel® Implicit SPMD Program Compiler (Intel® ISPC) provides wide vector performance tuning for compiled program objects.
Intel® ISPC automatically vectorizes and leverages Intel® Streaming SIMD Extensions, Intel® Advanced Vector Extensions, Intel® Advanced Vector Extensions 2 and Intel® Advanced Vector Extensions 512 instructions
that Render Kit programs can benefit from
.
These objects can be linked to larger C and C++ programs. Many Render Kit sample applications have two versions, one written in C/C++ and another in Intel ISPC and C/C++.
Intel® ISPC is not included in the
Render Kit
. By default, the
Render Kit
tutorial assets are set to be built with a system compiler.
If you want to use the
rkUtil
superbuild script to build the Intel oneAPI Rendering Toolkit, the Intel® ISPC is downloaded automatically. Using the
rkUtil
superbuild script is recommended for new and returning developers.
Using the Intel® ISPC is recommended to optimize application performance.
Intel ISPC can be installed from https://github.com/ispc/ispc/releases. Intel ISPC version 1.12.0 is recommended.
Recent versions of macOS* may restrict Intel ISPC binaries from execution. Run the following to disable execution restrictions:
sudo spctl --master-disable
For more security configuration options, use
man spctl
.

Set Environment Variables

To work at a Command Line Interface (CLI), you may configure the components of the oneAPI toolkits using environment variable script.
Option 1: Configure environment variables once per session
Option 1a
: Use the global environment script for Intel® oneAPI Toolkits once for your session. This sets variables for all installed components.
source <install-dir>/setvars.sh
where
<install-dit>
is the Intel oneAPI Toolkits installation directory. By default, it is
/opt/intel/oneapi/
.
Option 1b
: Run one of the component-specific environment scripts before running corresponding precompiled tutorial samples. The individual environment scripts are in the relative location of
env/vars.sh
for each component. By default, they are located at:
  • For Intel® OSPRay:
    /opt/intel/oneapi/ospray/latest/env/vars.sh
  • For Intel® Embree:
    /opt/intel/oneapi/embree/latest/env/vars.sh
  • For Intel® Open Image Denoise:
    /opt/intel/oneapi/oidn/latest/env/vars.sh
  • For Intel® Open Volume Kernel Library (Intel® Open VKL):
    /opt/intel/oneapi/openvkl/latest/env/vars.sh
  • For Intel® OSPRay Studio:
    /opt/intel/oneapi/ospray_studio/latest/env/vars.sh
For example, to set up environment variables for Intel Embree, run the following:
source /opt/intel/oneapi/embree/latest/env/vars.sh
Component scripts set the
DYLD_LIBRARY_PATH
variable to search directories with
oneTBB
libraries suitable for the tutorial programs. Within a bash terminal session, run precompiled samples only for one component, as
LD_LIBRARY_PATH
may cause a
oneTBB
mismatch if you have multiple
oneTBB
versions installed on your system.
Render Kit
programs typically use the following
oneTBB
libraries:
libtbb.so.2
,
libtbbmalloc.so.2
, and
libtbbmalloc_proxy.so.2
.
If your program execution results in segmentation faults or library-based symbol errors, consider using the option 1a to set environment variables. Use the
env -i
command to launch default shells.
Option 2: Configure environment variables to be set up automatically
Setting variables automatically in the shell session is not necessary and only recommended for advanced users of the
Intel® oneAPI Rendering Toolkit
.
If you choose this option to set the environment variables, make sure you set environment variables in the correct order that resolves your intended
oneTBB
dependency library
libtbb.so
.
You can use a component-specific script or a global script.
To set environment variables using component-specific scripts
:
  • To have the environment automatically set up for all projects, add a
    source <install_dir>/<component_dir>/latest/env/vars.sh
    component-specific command to a startup script where it will be invoked automatically. Replace
    <install_dir>
    with the path to your oneAPI install location and
    <component_dir>
    to the directory name for a specific component.
    For example, you can add the
    source <install_dir>/<component_dir>/latest/env/vars.sh
    command to your
    ~/.bashrc
    ,
    ~/.bashrc_profile
    , or
    ~/.profile
    file.
  • 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 that sources
    vars.sh
    (for more details, see /etc/profile.d/).
To set environment variables using the global script:
You can find the
setvars.sh
script in the root folder of your oneAPI installation, which is typically
/opt/intel/oneapi/
for sudo or root users and
~/intel/oneapi/
when installed as a normal user.
To have the environment automatically set up for projects, add a
source <install_dir>/setvars.sh
component-specific command to a startup script where it will be invoked automatically (replace
<install_dir>
with the path to your oneAPI install location).
Option 3: No environment variables
Setting environment variables in the Intel oneAPI Rendering Toolkit simplifies running sample applications. However, they are otherwise not absolutely required for building programs. Deployed applications can be built with a relative
rpath
for the local directory
.
that allows the dynamic linker to find required libraries.
  1. Build your programs with the
    rpath
    set similarly or to the local directory.
  2. Stage the desired version of the
    oneTBB
    runtime libraries along with resulting executables to disambiguate distributions of the
    oneTBB
    installed on the system.
Developers interested in this deployment are well suited to review the
superbuild
CMake script as part of the
rkUtil
component. See the Build Intel® oneAPI Rendering Toolkit Libraries for Linux OS article for details.

Feedback

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

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.