OSPRay

This is release v3.2.0 of Intel® OSPRay. For changes and new features see the changelog. Visit http://www.ospray.org for more information.

OSPRay Overview

Intel® OSPRay is an open source, scalable, and portable ray tracing engine for high-performance, high-fidelity visualization on Intel Architecture CPUs, Intel Xe GPUs, and ARM64 CPUs. OSPRay is part of the Intel Rendering Toolkit (Render Kit) and is released under the permissive Apache 2.0 license.

The purpose of OSPRay is to provide an open, powerful, and easy-to-use rendering library that allows one to easily build applications that use ray tracing based rendering for interactive applications (including both surface- and volume-based visualizations). OSPRay runs on anything from laptops, to workstations, to compute nodes in HPC systems.

OSPRay internally builds on top of Intel Embree, Intel Open VKL, and Intel Open Image Denoise. The CPU implementation is based on Intel ISPC (Implicit SPMD Program Compiler) and fully exploits modern instruction sets like Intel SSE4, AVX, AVX2, AVX-512 and NEON to achieve high rendering performance. Hence, a CPU with support for at least SSE4.1 is required to run OSPRay on x86_64 architectures, or a CPU with support for NEON is required to run OSPRay on ARM64 architectures.

OSPRay’s GPU implementation (beta status) is based on the SYCL cross-platform programming language implemented by Intel oneAPI Data Parallel C++ (DPC++) and currently supports Intel Arc™ GPUs on Linux and Windows, and Intel Data Center GPU Flex and Max Series on Linux, exploiting ray tracing hardware support.

OSPRay Support and Contact

OSPRay is under active development, and though we do our best to guarantee stable release versions a certain number of bugs, as-yet-missing features, inconsistencies, or any other issues are still possible. For any such requests or findings please use OSPRay’s GitHub Issue Tracker (or, if you should happen to have a fix for it, you can also send us a pull request).

To receive release announcements simply “Watch” the OSPRay repository on GitHub.

Building and Finding OSPRay

The latest OSPRay sources are always available at the OSPRay GitHub repository. The default master branch should always point to the latest bugfix release.

Prerequisites

OSPRay currently supports Linux, Mac OS X, and Windows. In addition, before you can build OSPRay you need the following prerequisites:

• You can clone the latest OSPRay sources via:

sh git clone https://github.com/ospray/ospray.git

• To build OSPRay you need CMake, any form of C++11 compiler (we recommend using GCC, but also support Clang, MSVC, and Intel® C++ Compiler (icc)), and standard Linux development tools.

• Additionally you require a copy of the Intel® Implicit SPMD Program Compiler (ISPC), version 1.23.0 or later. Please obtain a release of ISPC from the ISPC downloads page. If ISPC is not found by CMake its location can be hinted with the variable ISPC_EXECUTABLE.

• OSPRay builds on top of the Intel Rendering Toolkit (Render Kit) common library (rkcommon). The library provides abstractions for tasking, aligned memory allocation, vector math types, among others. For users who also need to build rkcommon, we recommend the default the Intel Threading Building Blocks (TBB) as tasking system for performance and flexibility reasons. TBB must be built from source when targeting ARM CPUs, or can be built from source as part of the superbuild. Alternatively you can set CMake variable RKCOMMON_TASKING_SYSTEM to OpenMP or Internal.

• OSPRay also heavily uses Intel Embree, installing version 4.3.3 or newer is required. If Embree is not found by CMake its location can be hinted with the variable embree_DIR.

• OSPRay supports volume rendering (enabled by default via OSPRAY_ENABLE_VOLUMES), which heavily uses Intel Open VKL, version 2.0.1 or newer is required. If Open VKL is not found by CMake its location can be hinted with the variable openvkl_DIR, or disable OSPRAY_ENABLE_VOLUMES.

• OSPRay also provides an optional module implementing the denoiser image operation, which is enabled by OSPRAY_MODULE_DENOISER. This module requires Intel Open Image Denoise in version 2.3.0 or newer. You may need to hint the location of the library with the CMake variable OpenImageDenoise_DIR.

• For the optional MPI modules (enabled by OSPRAY_MODULE_MPI), which provide the mpiOffload and mpiDistributed devices, you need an MPI library and Google Snappy.

• The optional example application, the test suit and benchmarks need some version of OpenGL and GLFW as well as GoogleTest and Google Benchmark

Depending on your Linux distribution you can install these dependencies using yum or apt-get. Some of these packages might already be installed or might have slightly different names.

Type the following to install the dependencies using yum:

sudo yum install cmake.x86_64
sudo yum install tbb.x86_64 tbb-devel.x86_64

Type the following to install the dependencies using apt-get:

sudo apt-get install cmake-curses-gui
sudo apt-get install libtbb-dev

Under Mac OS X these dependencies can be installed using MacPorts:

sudo port install cmake tbb

Under Windows please directly use the appropriate installers for CMake, TBB, ISPC (for your Visual Studio version) and Embree.

Additional Prerequisites for GPU Build

To build OSPRay’s GPU module you need

• a SYCL compiler, either the open source oneAPI DPC++ Compiler 2023-10-26 or the latest Intel oneAPI DPC++/C++ Compiler
• a recent CMake, version 3.25.3 or higher

CMake Superbuild

For convenience, OSPRay provides a CMake Superbuild script which will pull down OSPRay’s dependencies and build OSPRay itself. By default, the result is an install directory, with each dependency in its own directory.

Run with:

mkdir build
cd build
cmake [<OSPRAY_SOURCE_DIR>/scripts/superbuild]
cmake --build .

On Windows make sure to select a 64 bit generator, e.g.

cmake -G "Visual Studio 17 2022" [<OSPRAY_SOURCE_DIR>/scripts/superbuild]

The resulting install directory (or the one set with CMAKE_INSTALL_PREFIX) will have everything in it, with one subdirectory per dependency.

CMake options to note (all have sensible defaults):

CMAKE_INSTALL_PREFIX
will be the root directory where everything gets installed.

BUILD_JOBS
sets the number given to make -j for parallel builds.

INSTALL_IN_SEPARATE_DIRECTORIES
toggles installation of all libraries in separate or the same directory.

BUILD_OPENVKL
whether to enable volume rendering via Open VKL

BUILD_EMBREE_FROM_SOURCE
set to OFF will download a pre-built version of Embree.

BUILD_OIDN_FROM_SOURCE
set to OFF will download a pre-built version of Open Image Denoise.

OIDN_VERSION
determines which version of Open Image Denoise to pull down.

BUILD_OSPRAY_MODULE_MPI
set to ON to build OSPRay’s MPI module for data-replicated and distributed parallel rendering on multiple nodes.

BUILD_GPU_SUPPORT
enables beta GPU support, fetching the SYCL variants of the dependencies and builds OSPRAY_MODULE_GPU

BUILD_TBB_FROM_SOURCE
set to ON to build TBB from source (required for ARM support). The default setting is OFF.

For the full set of options, run:

ccmake [<OSPRAY_SOURCE_DIR>/scripts/superbuild]

or

cmake-gui [<OSPRAY_SOURCE_DIR>/scripts/superbuild]

Cross-Compilation with the Superbuild

The superbuild can be passed a CMake Toolchain file to configure for cross-compilation. This is done by passing the toolchain file when running cmake. When cross compiling it is also likely that you’ll want to build TBB and Embree from source to ensure they’re built for the correct target, rather than the target the Github binaries are built for. It may also be necessary to disable specific ISAs for the target by passing BUILD_ISA_<ISA_NAME>=OFF as well.

mkdir build
cd build
cmake --toolchain [toolchain_file.cmake] [path/to/this/directory]
    -DBUILD_TBB_FROM_SOURCE=ON \
    -DBUILD_EMBREE_FROM_SOURCE=ON \
    <other arguments>

While OSPRay supports ARM natively, it may be desirable to cross-compile it for x86_64 to run in Rosetta depending on the application integrating OSPRay. This can be done using the toolchain file toolchains/macos-rosetta.cmake, and by disabling all non-SSE ISAs when building. This can also be done by launching an x86_64 bash shell and then compiling as usual in this environment, which will cause the compilation chain to target x86_64. The BUILD_ISA_<ISA NAME>=OFF flags should be passed to disable all ISAs besides SSE4 for Rosetta:

arch -x86_64 bash
mkdir build
cd build
cmake [path/to/this/directory]
    -DBUILD_TBB_FROM_SOURCE=ON \
    -DBUILD_EMBREE_FROM_SOURCE=ON \
    -DBUILD_ISA_AVX=OFF \
    -DBUILD_ISA_AVX2=OFF \
    -DBUILD_ISA_AVX512=OFF \
    <other arguments>

Standard CMake Build

Compiling OSPRay on Linux and Mac OS X

Assuming the above requisites are all fulfilled, building OSPRay through CMake is easy:

• Create a build directory, and go into it

sh mkdir ospray/build cd ospray/build

(We do recommend having separate build directories for different configurations such as release, debug, etc.).

• The compiler CMake will use will default to whatever the CC and CXX environment variables point to. Should you want to specify a different compiler, run cmake manually while specifying the desired compiler. The default compiler on most linux machines is gcc, but it can be pointed to clang instead by executing the following:

sh cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ..

CMake will now use Clang instead of GCC. If you are OK with using the default compiler on your system, then simply skip this step. Note that the compiler variables cannot be changed after the first cmake or ccmake run.

• Open the CMake configuration dialog

sh ccmake ..

• Make sure to properly set build mode and enable the components you need, etc.; then type ’c’onfigure and ’g’enerate. When back on the command prompt, build it using

sh make

• You should now have libospray.[so,dylib] as well as a set of example applications.

Compiling OSPRay on Windows

On Windows using the CMake GUI (cmake-gui.exe) is the most convenient way to configure OSPRay and to create the Visual Studio solution files:

• Browse to the OSPRay sources and specify a build directory (if it does not exist yet CMake will create it).

• Click “Configure” and select as generator the Visual Studio version you have; OSPRay needs “Visual Studio 15 2017 Win64” or newer, 32
  bit builds are not supported, e.g., “Visual Studio 17 2022”.

• If the configuration fails because some dependencies could not be found then follow the instructions given in the error message, e.g., set the variable embree_DIR to the folder where Embree was installed and openvkl_DIR to where Open VKL was installed.

• Optionally change the default build options, and then click “Generate” to create the solution and project files in the build directory.

• Open the generated OSPRay.sln in Visual Studio, select the build configuration and compile the project.

Alternatively, OSPRay can also be built without any GUI, entirely on the console. In the Visual Studio command prompt type:

cd path\to\ospray
mkdir build
cd build
cmake -G "Visual Studio 17 2022" [-D VARIABLE=value] ..
cmake --build . --config Release

Use -D to set variables for CMake, e.g., the path to Embree with “-D embree_DIR=\path\to\embree”.

You can also build only some projects with the --target switch. Additional parameters after “--” will be passed to msbuild. For example, to build in parallel only the OSPRay library without the example applications use

cmake --build . --config Release --target ospray -- /m

Finding an OSPRay Install with CMake

Client applications using OSPRay can find it with CMake’s find_package() command. For example,

find_package(ospray 3.0.0 REQUIRED)

finds OSPRay via OSPRay’s configuration file osprayConfig.cmake[^1]. Once found, the following is all that is required to use OSPRay:

``` sh target_link_