View on GitHub

Embree

High Performance Ray Tracing Kernels

We recently released Embree v3.2.0!

Supported Platforms

Embree supports Windows (32-bit and 64-bit), Linux (64-bit), and macOS (64-bit). The code compiles with the Intel® Compiler, GCC, Clang, and the Microsoft Compiler.

Using the Intel® Compiler improves performance by approximately 10%. Performance also varies across different operating systems, with Linux typically performing best as it supports transparently transitioning to 2MB pages.

Embree is optimized for Intel CPUs supporting SSE, AVX, AVX2, and AVX-512 instructions, and requires at least a CPU with support for SSE2.

Downloading Embree

For Windows we provide Embree as MSI installer and ZIP files:

embree-3.2.0-x64.msi
embree-3.2.0.x64.windows.zip

For Linux we provide Embree as RPMs or as a tar.gz file:

embree-3.2.0.x86_64.rpm.tar.gz
embree-3.2.0.x86_64.linux.tar.gz

For macOS we provide Embree as PKG installer and as a tar.gz file:

embree-3.2.0.x86_64.pkg
embree-3.2.0.x86_64.macosx.tar.gz

For the first generation Intel® Xeon Phi™ coprocessor (codenamed Knights Corner) we provide Embree v2.9.0 precompiled for Linux as RPMs or as a tar.gz file:

embree-knc-2.9.0.x86_64.rpm.tar.gz
embree-knc-2.9.0.x86_64.linux.tar.gz

The source code of the latest Embree version can be downloaded here:

embree-3.2.0.zip
embree-3.2.0.tar.gz

You can access old Embree releases at https://github.com/embree/embree/releases.

Alternatively you can also use git to get the source code of Embree v3.2.0

$ git clone https://github.com/embree/embree.git embree
$ cd embree
$ git checkout v3.2.0

You can also check out the source code of Embree with subversion:

$ svn checkout https://github.com/embree/embree.git/tags/v3.2.0 embree
$ cd embree

If you encounter bugs please report them to the GitHub Issue Tracker for Embree.

Installation of Embree

Windows MSI Installer

You can install the Embree library using the Windows MSI installer embree-3.2.0-x64.msi. This will install the 64-bit Embree version by default in Program Files\Intel\Embree v3.2.0 x64.

You have to set the path to the bin folders manually to your PATH environment variable for applications to find Embree.

To compile applications with Embree using CMake, please have a look at the find_embree tutorial. To compile this tutorial, you need to set the embree_DIR CMake variable of this tutorial to Program Files\Intel\Embree v3.2.0 x64.

To uninstall Embree, open Programs and Features by clicking the Start button, clicking Control Panel, clicking Programs, and then clicking Programs and Features. Select Embree 3.2.0 x64 and uninstall it.

Windows ZIP File

Embree is also delivered as a ZIP file embree-3.2.0.x64.windows.zip. After unpacking this ZIP file, you should set the path to the lib folder manually to your PATH environment variable for applications to find Embree. To compile applications with Embree, you also have to set the Include Directories path in Visual Studio to the include folder of the Embree installation.

If you plan to ship Embree with your application, best use the Embree version from this ZIP file.

Linux RPMs

Uncompress the tar.gz file embree-3.2.0.x86_64.rpm.tar.gz to obtain the individual RPM files:

tar xzf embree-3.2.0.x86_64.rpm.tar.gz

To install Embree using the RPM packages on your Linux system, type the following:

sudo rpm --install embree-lib-3.2.0-1.x86_64.rpm
sudo rpm --install embree-devel-3.2.0-1.noarch.rpm
sudo rpm --install embree-examples-3.2.0-1.x86_64.rpm

You also have to install the Intel® Threading Building Blocks (TBB) using yum:

sudo yum install tbb.x86_64 tbb-devel.x86_64

On Debian-based Linux distributions you first need to convert the RPM filed into DEB files using the alien tool:

sudo apt-get install alien dpkg-dev debhelper build-essential

sudo alien embree-lib-3.2.0-1.x86_64.rpm
sudo alien embree-devel-3.2.0-1.noarch.rpm
sudo alien embree-examples-3.2.0-1.x86_64.rpm

sudo dpkg -i embree-devel_3.2.0-2_all.deb
sudo dpkg -i embree-examples_3.2.0-2_amd64.deb
sudo dpkg -i embree-lib_3.2.0-2_amd64.deb

Also install the Intel® Threading Building Blocks (TBB) using apt-get:

sudo apt-get install libtbb-dev

Alternatively you can download the latest TBB version from https://www.threadingbuildingblocks.org/download and set the LD_LIBRARY_PATH environment variable to point to the TBB library.

Note that the Embree RPMs are linked against the TBB version coming with CentOS. This older TBB version is missing some features required to get optimal build performance, and does not support building of scenes lazily during rendering. To get a full featured Embree, please install using the tar.gz files, which always ship with the latest TBB version.

Under Linux, Embree is installed by default in the /usr/lib64 and /usr/include directories. This way applications will find Embree automatically. The Embree tutorials are installed into the /usr/bin/embree3 folder. Specify the full path to the tutorials to start them.

To uninstall Embree, just execute the following:

sudo rpm --erase embree-lib-3.2.0-1.x86_64
sudo rpm --erase embree-devel-3.2.0-1.noarch
sudo rpm --erase embree-examples-3.2.0-1.x86_64

Linux tar.gz Files

The Linux version of Embree is also delivered as a tar.gz file: embree-3.2.0.x86_64.linux.tar.gz. Unpack this file using tar and source the provided embree-vars.sh (if you are using the bash shell) or embree-vars.csh (if you are using the C shell) to set up the environment properly:

tar xzf embree-3.2.0.x64.linux.tar.gz
source embree-3.2.0.x64.linux/embree-vars.sh

If you want to ship Embree with your application, best use the Embree version provided in the tar.gz file.

We recommend adding a relative RPATH to your application that points to the location where Embree (and TBB) can be found, e.g. $ORIGIN/../lib.

macOS PKG Installer

To install the Embree library on your macOS system use the provided package installer inside embree-3.2.0.x86_64.dmg. This will install Embree by default into /opt/local/lib and /opt/local/include directories. The Embree tutorials are installed into the /Applications/Embree3 directory.

You also have to install the Intel® Threading Building Blocks (TBB) using MacPorts:

sudo port install tbb

Alternatively you can download the latest TBB version from https://www.threadingbuildingblocks.org/download and set the DYLD_LIBRARY_PATH environment variable to point to the TBB library.

To uninstall Embree, execute the uninstaller script /Applications/Embree3/uninstall.command.

macOS tar.gz file

The macOS version of Embree is also delivered as a tar.gz file: embree-3.2.0.x86_64.macosx.tar.gz. Unpack this file using tar and source the provided embree-vars.sh (if you are using the bash shell) or embree-vars.csh (if you are using the C shell) to set up the environment properly:

tar xzf embree-3.2.0.x64.macosx.tar.gz
source embree-3.2.0.x64.macosx/embree-vars.sh

If you want to ship Embree with your application, please use the Embree library of the provided tar.gz file. The library name of that Embree library is of the form @rpath/libembree.3.dylib (and similar also for the included TBB library). This ensures that you can add a relative RPATH to your application that points to the location where Embree (and TBB) can be found, e.g. @loader_path/../lib.

Compiling Embree

We recommend to use CMake to build Embree. Do not enable fast-math optimizations; these might break Embree.

Linux and macOS

To compile Embree you need a modern C++ compiler that supports C++11. Embree is tested with Intel® Compiler 17.0 (Update 1), Intel® Compiler 16.0 (Update 1), Clang 3.8.0 (supports AVX2), Clang 4.0.0 (supports AVX512) and GCC 5.4.0. If the GCC that comes with your Fedora/Red Hat/CentOS distribution is too old then you can run the provided script scripts/install_linux_gcc.sh to locally install a recent GCC into $HOME/devtools-2.

Embree supports using the Intel® Threading Building Blocks (TBB) as the tasking system. For performance and flexibility reasons we recommend to use Embree with the Intel® Threading Building Blocks (TBB) and best also use TBB inside your application. Optionally you can disable TBB in Embree through the EMBREE_TASKING_SYSTEM CMake variable.

Embree supports the Intel® SPMD Program Compiler (ISPC), which allows straightforward parallelization of an entire renderer. If you do not want to use ISPC then you can disable EMBREE_ISPC_SUPPORT in CMake. Otherwise, download and install the ISPC binaries (we have tested ISPC version 1.9.1) from ispc.github.io. After installation, put the path to ispc permanently into your PATH environment variable or you need to correctly set the ISPC_EXECUTABLE variable during CMake configuration.

You additionally have to install CMake 2.8.11 or higher and the developer version of GLUT.

Under macOS, all these dependencies can be installed using MacPorts:

sudo port install cmake tbb-devel glfw-devel

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
sudo yum install tbb-devel
sudo yum install glfw-devel

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

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

Finally you can compile Embree using CMake. Create a build directory inside the Embree root directory and execute ccmake .. inside this build directory.

mkdir build
cd build
ccmake ..

Per default CMake will use the compilers specified with the CC and CXX environment variables. Should you want to use a different compiler, run cmake first and set the CMAKE_CXX_COMPILER and CMAKE_C_COMPILER variables to the desired compiler. For example, to use the Intel® Compiler instead of the default GCC on most Linux machines (g++ and gcc), execute

cmake -DCMAKE_CXX_COMPILER=icpc -DCMAKE_C_COMPILER=icc ..

Similarly, to use Clang set the variables to clang++ and clang, respectively. Note that the compiler variables cannot be changed anymore after the first run of cmake or ccmake.

Running ccmake will open a dialog where you can perform various configurations as described below in CMake Configuration. After having configured Embree, press c (for configure) and g (for generate) to generate a Makefile and leave the configuration. The code can be compiled by executing make.

make

The executables will be generated inside the build folder. We recommend to finally install the Embree library and header files on your system. Therefore set the CMAKE_INSTALL_PREFIX to /usr in cmake and type:

sudo make install

If you keep the default CMAKE_INSTALL_PREFIX of /usr/local then you have to make sure the path /usr/local/lib is in your LD_LIBRARY_PATH.

You can also uninstall Embree again by executing:

sudo make uninstall

If you cannot install Embree on your system (e.g. when you don’t have administrator rights) you need to add embree_root_directory/build to your LD_LIBRARY_PATH.

Windows

Embree is tested under Windows using the Visual Studio 2017, Visual Studio 2015 (Update 1) compiler (Win32 and x64), Visual Studio 2013 (Update 5) compiler (Win32 and x64), Intel® Compiler 17.0 (Update 1) (Win32 and x64), Intel® Compiler 16.0 (Update 1) (Win32 and x64), and Clang 3.9 (Win32 and x64). Using the Visual Studio 2015 compiler, Visual Studio 2013 compiler, Intel® Compiler, and Clang you can compile Embree for AVX2. To compile Embree for AVX-512 you have to use the Intel® Compiler.

Embree supports using the Intel® Threading Building Blocks (TBB) as the tasking system. For performance and flexibility reasons we recommend to use Embree with the Intel® Threading Building Blocks (TBB) and best also use TBB inside your application. Optionally you can disable TBB in Embree through the EMBREE_TASKING_SYSTEM CMake variable.

Embree will either find the Intel® Threading Building Blocks (TBB) installation that comes with the Intel® Compiler, or you can install the binary distribution of TBB directly from www.threadingbuildingblocks.org into a folder named tbb into your Embree root directory. You also have to make sure that the libraries tbb.dll and tbb_malloc.dll can be found when executing your Embree applications, e.g. by putting the path to these libraries into your PATH environment variable.

Embree supports the Intel® SPMD Program Compiler (ISPC), which allows straightforward parallelization of an entire renderer. When installing ISPC, make sure to download an ISPC version from ispc.github.io that is compatible with your Visual Studio version. There are two ISPC versions, one for Visual Studio 2013 and earlier, and one for Visual Studio 2015 and later. When using the wrong ISPC version you will get link errors. After installation, put the path to ispc.exe permanently into your PATH environment variable or you need to correctly set the ISPC_EXECUTABLE variable during CMake configuration. We have tested ISPC version 1.9.1. If you do not want to use ISPC then you can disable EMBREE_ISPC_SUPPORT in CMake.

You additionally have to install CMake (version 2.8.11 or higher). Note that you need a native Windows CMake installation, because CMake under Cygwin cannot generate solution files for Visual Studio.

Using the IDE

Run cmake-gui, browse to the Embree sources, set the build directory and click Configure. Now you can select the Generator, e.g. “Visual Studio 12 2013” for a 32-bit build or “Visual Studio 12 2013 Win64” for a 64-bit build.

To use a different compiler than the Microsoft Visual C++ compiler, you additionally need to specify the proper compiler toolset through the option “Optional toolset to use (-T parameter)”. E.g. to use Clang for compilation set the toolset to “LLVM-vs2013”, to use the Intel® Compiler 2017 for compilation set the toolset to “Intel C++ Compiler 17.0”.

Do not change the toolset manually in a solution file (neither through the project properties dialog, nor through the “Use Intel Compiler” project context menu), because then some compiler specific command line options cannot be set by CMake.

Most configuration parameters described in the CMake Configuration can be set under Windows as well. Finally, click “Generate” to create the Visual Studio solution files.

The following CMake options are only available under Windows:

Use the generated Visual Studio solution file embree2.sln to compile the project. To build Embree with support for the AVX2 instruction set you need at least Visual Studio 2013 (Update 4).

We recommend enabling syntax highlighting for the .ispc source and .isph header files. To do so open Visual Studio, go to Tools ⇒ Options ⇒ Text Editor ⇒ File Extension and add the isph and ispc extensions for the “Microsoft Visual C++” editor.

Using the Command Line

Embree can also be configured and built without the IDE using the Visual Studio command prompt:

cd path\to\embree
mkdir build
cd build
cmake -G "Visual Studio 12 2013 Win64" ..
cmake --build . --config Release

To use the Intel® Compiler, set the proper toolset, e.g. for Intel Compiler 17.0:

cmake -G "Visual Studio 12 2013 Win64" -T "Intel C++ Compiler 17.0" ..
cmake --build . --config Release

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

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

CMake Configuration

The default CMake configuration in the configuration dialog should be appropriate for most usages. The following list describes all parameters that can be configured in CMake:

Using Embree

The most convenient way of using Embree is through CMake. Just let CMake find Embree using the FIND_PACKAGE function inside your CMakeLists.txt file:

 FIND_PACKAGE(embree 3.0 REQUIRED)

If you installed Embree using the Linux RPM or macOS PKG installer, this will automatically find Embree. If you used the zip or tar.gz files to extract Embree, you need to set the embree_DIR variable to the folder you extracted Embree to. If you used the Windows MSI installer, you need to set embree_DIR to point to the Embree install location (e.g. C:\Program Files\Intel\Embree3).

The FIND_PACKAGE CMake function will set the EMBREE_INCLUDE_DIRS variable to point to the directory containing the Embree headers. You should add this folder to the include directories of your build:

INCLUDE_DIRECTORIES(${EMBREE_INCLUDE_DIRS})

Further, the EMBREE_LIBRARY variable will point to the Embree library to link against. Link against Embree the following way:

TARGET_LINK_LIBRARIES(application ${EMBREE_LIBRARY})

Now please have a look at the [Embree Tutorials] source code and the Embree API section to get started.