View on GitHub

Embree

High Performance Ray Tracing Kernels

We recently released Embree v2.6.2!

Supported Platforms

Embree supports Windows (32 bit and 64 bit), Linux (64 bit) and Mac OS X (64 bit). The code compiles with the Intel Compiler, GCC, CLANG and the Microsoft Compiler. Embree is tested with Intel Compiler 15.0.2, CLANG 3.4.2, GCC 4.8.2, and Visual Studio 12 2013. Using the Intel Compiler improves performance by approximately 10%.

Performance also varies across different operating systems. Embree is optimized for Intel CPUs supporting SSE, AVX, and AVX2 instructions, and requires at least a CPU with support for SSE2.

The Xeon Phi version of Embree only works under Linux in 64 bit mode. For compilation of the the Xeon Phi code the Intel Compiler is required. The host side code compiles with GCC, CLANG, and the Intel Compiler.

Downloading Embree

For Windows we provide an installer for precompiled 64 bit and 32 bit Embree binaries as well as ZIP files:

embree-2.6.2-x64.exe
embree-2.6.2-win32.exe

embree-2.6.2.x64.windows.zip
embree-2.6.2.win32.windows.zip

For Linux we provide Embree precompiled for 64 bit as RPMs or as TGZ file:

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

For Mac OS X we provide Embree as an installer and as a TGZ file:

embree-2.6.2.x86_64.dmg
embree-2.6.2.x86_64.macosx.tar.gz

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

embree-2.6.2.zip
embree-2.6.2.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 v2.6.2

$ git clone https://github.com/embree/embree.git embree
$ cd embree
$ git checkout v2.6.2

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

$ svn checkout https://github.com/embree/embree.git/tags/v2.6.2 embree
$ cd embree

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

Installation of Embree

Windows Installer

You can install the 64 bit version of the Embree library using the Windows installer application embree-2.6.2-x64.exe. This will install the 64 bit Embree version by default in Program Files\Intel\Embree v2.6.2 x64. To install the 32 bit Embree library use the embree-2.6.2-win32.exe installer. This will install the 32 bit Embree version by default in Program Files\Intel\Embree v2.6.2 win32 on 32 bit systems and Program Files (x86)\Intel\Embree v2.6.2 win32 on 64 bit systems.

You have to 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.

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

Windows ZIP File

Embree is also delivered as a ZIP file for 64 bit embree-2.6.2.x64.windows.zip and 32 bit embree-2.6.2.win32.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-2.6.2.x86_64.rpm.tar.gz to obtain the individual RPM files:

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

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

sudo rpm --install embree-lib-2.6.2-1.x86_64.rpm
sudo rpm --install embree-devel-2.6.2-1.x86_64.rpm
sudo rpm --install embree-examples-2.6.2-1.x86_64.rpm

To also install the Intel® Xeon Phi™ version of Embree additionally install the following Xeon Phi™ RPMs:

sudo rpm --install --nodeps embree-lib_xeonphi-2.6.2-1.x86_64.rpm
sudo rpm --install --nodeps embree-examples_xeonphi-2.6.2-1.x86_64.rpm

To use the Xeon Phi™ version of Embree you additionally have configure your SINK_LD_LIBRARY_PATH to point to /usr/lib:

export SINK_LD_LIBRARY_PATH=/usr/local:${SINK_LD_LIBRARY_PATH}

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

sudo yum install tbb.x86_64 tbb-devel.x86_64

or via 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/lib and /usr/include directories. This way applications will find Embree automatically. The Embree tutorials are installed into the /usr/bin/embree-2.6.2 folder. Specify the full path to the tutorials to start them.

To uninstall Embree again just execute the following:

sudo rpm --erase embree-lib-2.6.2-1.x86_64
sudo rpm --erase embree-devel-2.6.2-1.x86_64
sudo rpm --erase embree-examples-2.6.2-1.x86_64

If you also installed the Xeon Phi™ RPMs you have to uninstall them too:

sudo rpm --erase embree-lib_xeonphi-2.6.2-1.x86_64
sudo rpm --erase embree-examples_xeonphi-2.6.2-1.x86_64

Linux tar.gz files

The Linux version of Embree is also delivered as a tar.gz file embree-2.6.2.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 setup the environment properly:

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

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

Mac OS X PKG Installer

To install the Embree library on your Mac OS X system use the provided package installer inside embree-2.6.2.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/Embree2 folder.

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 again execute the uninstaller script /Applications/embree-2.6.2/uninstall.command.

Mac OS X tar.gz file

The Mac OS X version of Embree is also delivered as a tar.gz file embree-2.6.2.x86_64.macosx.tar.gz. Unpack this file using tar and 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 setup the environment properly:

tar xzf embree-2.6.2.x64.macosx.tar.gz
source embree-2.6.2.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 does not contain any global path and also links against TBB without global path. This ensures that the Embree (and TBB) library that you put next to your application executable is used.

Linking ISPC applications with Embree

The precompiled Embree library uses the multi-target mode of ISPC. For your ISPC application to properly link against Embree you also have to enable this mode. You can do this by specifying multiple targets when compiling your application with ISPC, e.g.:

ispc --target sse2,sse4,avx,avx2 -o code.o code.ispc

Compiling Embree

Linux and Mac OS X

To compile Embree you need a modern C++ compiler that supports C++11. Embree is tested with Intel® Compiler 15.0.2, CLANG 3.4.2, and GCC 4.8.2. 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 to use the Intel® Threading Building Blocks (TBB) as 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 RTCORE_TASKING_SYSTEM CMake variable.

Embree supported the Intel® SPMD Program Compiler (ISPC), which allows straight forward parallelization of an entire renderer. If you do not want to use ISPC then you can disable ENABLE_ISPC_SUPPORT in CMake. Otherwise, download and install the ISPC binaries (we have tested ISPC version 1.8.2) 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 Mac OS X, all these dependencies can be installed using MacPorts:

sudo port install cmake tbb freeglut

Depending on you 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
sudo yum install freeglut.x86_64 freeglut-devel.x86_64
sudo yum install libXmu.x86_64 libXi.x86_64
sudo yum install libXmu-devel.x86_64 libXi-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
sudo apt-get install freeglut3-dev
sudo apt-get install libxmu-dev libxi-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 ..

This will open a configuration dialog where you can perform various configurations as described below. 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 (and SINK_LD_LIBRARY_PATH in case you want to use Embree on Intel® Xeon Phi™ coprocessors).

Intel® Xeon Phi™ coprocessor

Embree supports the Intel® Xeon Phi™ coprocessor under Linux. To compile Embree for Xeon Phi you need to enable the XEON_PHI_ISA option in CMake and have the Intel Compiler and the Intel® Manycore Platform Software Stack (Intel® MPSS) installed.

Enabling the buffer stride feature reduces performance for building spatial hierarchies on Xeon Phi. Under Xeon Phi the Intel® Threading Building Blocks (TBB) tasking system is not supported, and the implementation will always use some internal tasking system.

Windows

To compile Embree under Windows you need Visual Studio 2013 or Visual Studio 2012. Under Visual Studio 2013 you can enable AVX2 in CMake, however, Visual Studio 2012 supports at most AVX.

Embree supports to use the Intel® Threading Building Blocks (TBB) as 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 RTCORE_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 supported the Intel® SPMD Program Compiler (ISPC), which allows straight forward parallelization of an entire renderer. If you do not want to use ISPC then you can disable ENABLE_ISPC_SUPPORT in CMake. Otherwise, download and install the ISPC binaries (we have tested ISPC version 1.8.2) from ispc.github.io. 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.

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. Most configuration parameters described for the Linux build can be set under Windows as well. Finally, click “Generate” to create the Visual Studio solution files.

Windows-specific CMake build options for Embree.
Option Description Default
CMAKE_CONFIGURATION_TYPE List of generated configurations. Debug;Release;RelWithDebInfo
USE_STATIC_RUNTIME Use the static version of the C/C++ runtime library. OFF

For compilation of Embree under Windows use the generated Visual Studio solution file embree2.sln. The solution is by default setup to use the Microsoft Compiler. You can switch to the Intel Compiler by right clicking onto the solution in the Solution Explorer and then selecting the Intel Compiler. We recommend using 64 bit mode and the Intel Compiler for best performance.

To build Embree with support for the AVX2 instruction set you need at least Visual Studio 2013 Update 4. When switching to the Intel Compiler to build with AVX2 you currently need to manually remove the switch /arch:AVX2 from the embree_avx2 project, which can be found under Properties ⇒ C/C++ ⇒ All Options ⇒ Additional Options.

To build all projects of the solution it is recommend to build the CMake utility project ALL_BUILD, which depends on all projects. Using “Build Solution” would also build all other CMake utility projects (such as INSTALL), which is usually not wanted.

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 extension 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 switch to the Intel Compiler use

ICProjConvert150 embree2.sln /IC /s /f

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 table describes all parameters that can be configured in CMake:

CMake build options for Embree.
Option Description Default
CMAKE_BUILD_TYPE Can be used to switch between Debug mode (Debug), Release mode (Release), and Release mode with enabled assertions and debug symbols (RelWithDebInfo). Release
COMPILER Select either GCC, ICC, or CLANG as compiler. GCC
ENABLE_ISPC_SUPPORT Enables ISPC support of Embree. ON
ENABLE_STATIC_LIB Builds Embree as a static library. OFF
ENABLE_TUTORIALS Enables build of Embree tutorials. ON
ENABLE_XEON_PHI_SUPPORT Enables generation of the Xeon Phi version of Embree. OFF
RTCORE_BACKFACE_CULLING Enables backface culling, i.e. only surfaces facing a ray can be hit. OFF
RTCORE_BUFFER_STRIDE Enables the buffer stride feature. ON
RTCORE_INTERSECTION_FILTER Enables the intersection filter feature. ON
RTCORE_RAY_MASK Enables the ray masking feature. OFF
RTCORE_IGNORE_INVALID_RAYS Makes code robust against the risk of full-tree traversals caused by invalid rays (e.g. rays containing INF/NaN as origins). OFF
RTCORE_TASKING_SYSTEM Chooses between Intel® Threading Building Blocks (TBB) or an internal tasking system (INTERNAL). TBB
XEON_ISA Select highest supported ISA on Intel® Xeon® CPUs (SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX-I, AVX2, or AVX512). AVX2