Getting Started

Content of this page: Instructions on how to obtain, build, and use Visionaray.

Note that the current version of Visionaray is an early preview. At this stage, the framework, including the API, are likely to undergo frequent changes.

Setting up Build Requirements

Ubuntu Linux

All build dependencies for Ubuntu Linux 14.04 64-bit can be installed via aptitude. The following command installs the tools and libraries that are necessary to build Visionaray:

sudo apt-get install git build-essential cmake libboost-all-dev libglew-dev libxi-dev libxmu-dev freeglut3-dev

Setting up the build requirements on other Linux distributions should work quite similar but is tested less often. Please make sure to have a fairly new version of the GNU compiler. Version 4.8.4 that ships with Ubuntu 14.04 64-bit is known to work, while version 4.6 that ships with older Ubuntu versions does not work.

Mac OS X 10.10 with Homebrew

Under Mac OS X 10.10, you need to install Xcode from the Mac App Store. You will also need the Xcode command line tools, which need to be installed separately. To do so, with Xcode properly installed, open a terminal and type:

gcc

If the command line tools are not yet installed, a dialog will guide you through the installation. Otherwise, the gcc command will terminate with an error message, which can safely be ignored.

All additional dependencies can be installed via homebrew. You can use the following command:

brew install git cmake boost glew

The Visionaray viewer application uses the GLUT library to create an OpenGL window. Under Mac OS X, it is just fine to use the framework version that ships with Xcode.

Microsoft Windows

We are still working on this, so please check back soon.

Getting Visionaray

To get a copy of Visionaray, clone from the public git repository. The Visionaray viewer application uses the CmdLine library for command line parsing. CmdLine is integrated as a git submodule, so make sure to also initialize the git submodules. This can be achieved using the following commands:

git clone https://github.com/szellmann/visionaray.git
cd visionaray
git submodule update --init --recursive

Building and Installing Visionaray

Linux and Mac OS X

Building Visionaray should work pretty similar under both Linux and Mac OS X. We recommend building Visionaray on a command line. In general, building with Xcode (by throwing in a "-G Xcode" as a cmake argument) should work, but is rarely tested and thus not recommended.

On a command line, if necessary, switch to the directory you just cloned Visionaray to, and create a directory for an out-of-source build. Then invoke cmake from in there. Cmake will generate a Makefile in the build directory, which can be processed by the make command.

cd visionaray
mkdir build

cd build

cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-std=c++11 -msse4.1"
make
make install

Note the additional arguments to the cmake command. Visionaray requires building with C++-11 enabled. When built without optimizations (e.g. CMAKE_BUILD_TYPE empty - this is the default - or "Debug"), compilers will typically (amongst others) perform no inlining, which will have a severe performance impact. You also have to specify an architecture flag to the compiler, so that it can optimize for a certain instruction set architecture (ISA). On modern architectures, "-mavx2", "-mavx", or "-msse4.1" are adequate choices. For a list of ISAs supported by your computer, under Linux you can e.g. inspect "/proc/cpuinfo". "-msse4.1" should be available on most Intel CPUs from 2010 or newer. We do not recommend to use an older CPU, nor do we test or optimize for older architectures.

By default, Visionaray is installed to /usr/local. You can influence this by setting the cmake variable CMAKE_INSTALL_PREFIX appropriately (e.g. by appending -DCMAKE_INSTALL_PREFIX=path_to_install_dir to the cmake command from above).

Microsoft Windows

We are still working on this, so please check back soon.

Building with NVIDIA CUDA support

When compiled with NVIDIA CUDA support enabled, the Visionaray viewer application and some example programs may benefit from GPU acceleration on NVIDIA GPUs. NVIDIA CUDA builds can be enabled by adjusting the cmake variable VSNRAY_ENABLE_CUDA in the build directory. This can e.g. be accomplished by additionally passing -DVSNRAY_ENABLE_CUDA=ON to the cmake command, by editing the variable in the file CMakeCache.txt in the build directory, or by using a CMake application such as the CMake GUI or ccmake.

Legacy support for NVIDIA CUDA has low priority with Visionaray, the API is typically tested against the latest versions of NVIDIA CUDA.

Visionaray requires a version of the NVIDIA CUDA Toolkit that supports C++-11. On Linux or Mac OS X, adjust the cmake variable CUDA_NVCC_FLAGS to include -std=c++11. On Mac OS X with clang, the nvcc compiler does not pass the host compiler flags through to the host compiler; in order to obtain optimized binaries under Mac OS X, it is recommended to pass optimization flags to the host compiler explicitly: CUDA_NVCC_FLAGS:STRING=-std=c++11 -Xcompiler="-O3".

Building the Examples

Visionaray example programs serve as additional documentation for developers. Compiling the example programs is deactivated by default, but can be enabled by additionally passing -DVSNRAY_ENABLE_EXAMPLES=ON to the cmake command, or editing the variable VSNRAY_ENABLE_EXAMPLES in the file CMakeCache.txt with a text editor or using a CMake application.

Using Visionaray

... as a C++ library

Visionaray is primarily meant to be used as a ray tracing library and framework for developers. Doing so is documented in the Developer Guide.

... as a rudimentary wavefront obj viewer

Visionaray comes with a rudimentary wavefront obj viewer that can do ray casting, ray tracing, and path tracing. The viewer application is primarily meant for development and debugging, so please have this in mind when you use it for anything special. Make sure that the directory where the Visionaray executables are installed to (default: /usr/local/bin) is appended to the PATH environment variable. Then you can invoke the viewer as follows:

vsnray-viewer <filename.obj>

where filename.obj is a wavefront obj 3-D file containing geometry that is made up of polygons. For a complete list of command line arguments, please refer to the help dialog of the viewer application.

The viewer supports the following mouse interaction modes and keyboard shortcuts:

• LMB: Rotate the scene.
• MMB: Pan the scene (Mac OS X: LMB + Key-ALT).
• RMB: Zoom into the scene.
• Key-1: Switch to ray casting algorithm (default).
• Key-2: Switch to ray tracing algorithm.
• Key-3: Switch to path tracing algorithm.
• Key-4: Switch to BVH cost debugging algorithm.
• Key-b: Toggle displaying outlines of the BVH.
• Key-c: Toggle color space (RGB|sRGB).
• Key-h: Toggle visibility of head up display.
• Key-m: Switch between CPU mode and GPU mode (must be compiled with CUDA).
• Key-p: Make a screenshot and store it in "screenshot.pnm".
• Key-s: Toggle supersampling anti-aliasing mode. Only applies to ray casting and ray tracing algorithm (simple|whitted). Supported modes: 1x, 2x, 4x, and 8x supersampling.
• Key-u: Store the current camera in the working directory (visionaray-camera.txt).
• Key-v: Load the file "visionaray-camera.txt" from the current working directory, if it exists, and adjust the camera accordingly.
• Key-F5: Toggle full screen mode.
• Key-ESC: Exit full screen mode.
• Key-Space: Toggle path tracing convergence frame rendering paused or active.
• Key-q: Quit viewer application.