Building pbrt-v2

pbrt is designed to be easily ported to various platforms; the authors regularly compile it on Mac OS X, Windows, and a variety of Linux variants. pbrt users have sent patches to ensure that it compiles cleanly on FreeBSD, OpenBSD, and other systems. We will happily incorporate patches to make the system build on other platforms! (Please send patches or other notes about issues with building pbrt to [email protected].)

Linux, OS X, and other Unix systems

On Linux, OS X, and other Unix platforms, pbrt can be compiled with either the provided Makefile or the provided SCons build files (see scons.org for information about SCons). Please see the notes below about installing OpenEXR libraries on your system before building pbrt.

The SCons build files build both debug and release configurations of the system, while the Makefile only builds a release build. See comment at the top of the Makefile for how to modify it to do a debug build instead.

When using the Makefiles or SCons files, there are two important build configuration options: whether or not the OpenEXR and TIFF image formats are supported by the system or not, and how pbrt collects and reports statistics.

OpenEXR

If you have the OpenEXR image library installed, then pbrt will read and write OpenEXR format images. A number of the example scenes use OpenEXR image files. If you do have OpenEXR installed, then PBRT_HAS_OPENEXR should be #defined and the paths to the OpenEXR headers and libraries should be set in the build rules as appropriate.

On Mac OS X and Linux, OpenEXR compiles easily from the distribution from the OpenEXR website. Alternatively, most package or "ports" systems provide an OpenEXR installation. Specifically:

• On Ubuntu, run sudo apt-get install libopenexr-dev.
• On OS X with Homebrew installed, run brew install openexr.

(Please send [email protected] a note if you can tell us equivalent commands on other systems so that we can add them here!)

TIFF

We provide a utility program to convert from high dynamic range EXR images to low dynamic range TIFF images, exrtotiff. This program includes a rudimentary tone mapping pipeline and support for image bloom and gamma correction. To build this program, modify the user configuration section appropriately in either Makefile or SCons file (depending on how you're building the system.) There is not currently any support for building this from the MSVC solution file on Windows.

More comprehensive sets of programs to work with EXR images are available from scanline.ca/exrtools and pfstools.sourceforge.net.

Probes and Statistics

pbrt no longer collects runtime rendering statistics by default. (Updating shared statistics counters can cause a substantial performance impact with multi-threaded execution.) To override this, change the definition of the PBRT_PROBES_NONE preprocessor #define to either PBRT_PROBES_DTRACE or PBRT_PROBES_COUNTERS.

If your system supports dtrace (OSX, FreeBSD, and Solaris, currently, then pbrt is instrumented to provide a large number of dtrace probes that can be analyzed with dtrace scripts; building with dtrace support is supported if you set the PBRT_PROBES_DTRACE preprocessor #define. See the dtrace/ directory for a number of example dtrace scripts to use with pbrt.

Alternatively, PBRT_PROBES_COUNTERS can be set to compile the system to gather a number of statistics with shared counters, incurring the corresponding performance penalty.

OSX: XCode

In addition to the Makefile and SCons files described in the "Linux" section, there is also is also an XCode project file for Mac OS X, pbrt.xcodeproj.

By default, the XCode project file builds pbrt without support for reading or writing OpenEXR images. To add support for OpenEXR, first install OpenEXR (see the instructions above), and then follow these steps:

1. In the pbrt project build settings, add PBRT_HAS_OPENEXR to the "Preprocessor Macros" field. Some pbrt source files check whether this flag is defined and only include OpenEXR stuff if it is.
2. In the "Header Search Paths" field, add /usr/local/include/OpenEXR, /usr/include/OpenEXR, and /opt/local/include/OpenEXR (or just whichever one contains your OpenEXR installation, if you know that). This tells XCode where to look for the OpenEXR header files that pbrt refers to.
3. In the "Other Linker Flags" field, add -lIex -lIlmImf -lIlmThread -lImath -lIex -lHalf -lz. This tells XCode to link agains those seven libraries, which contain all the OpenEXR code and necessary supporting code.
4. In the "Library Search Paths" field, add /usr/local/lib and /opt/local/lib (or, again, just the one that contains your installation). This tells XCode where to look for the libraries specified in the previous step.

Windows: Visual Studio

There is not currently support for building pbrt with the Cygwin gcc compiler, but patches would be happily accepted.

To build pbrt on Windows:

• Open either the src/pbrt.vs2010/pbrt.sln or src/pbrt.vs2008/pbrt.sln Visual Studio solution file, depending on which version of MSVC you have installed.
• Select either Debug or Release, and x86 (win32) or x64.
• Build the solution.

To run pbrt, run the desired executable or program in the top-level bin/ directory of the pbrt distribution (pbrt-dist/bin).

To debug pbrt, first select the Debug configuration for either the x86 or x64 platform. Then, start the program in Visual Studio with debugging.

The parsing code

If you need to modify the pbrt input file parsing code, follow these steps first:

• Install Bison and Flex programs if they are not already installed. Choose either Cygwin or GnuWin32; either one will work.
  • Option A: GnuWin32: install Bison and Flex via setup packages.
  • Option B: Cygwin: install Cygwin with Bison and Flex packages. These may not be selected by default, so be sure to select them.
  • Important note: Do not install under "Program Files" or "Program Files (x86)". The installation path should not contain any spaces. Use C:\cygwin or C:\gnuwin32, for example.
• Add Bison and Flex executable paths to the system PATH so that they can be run from any directory or location:
  • Right-click "My Computer" or "Computer".
  • Click Properties.
  • Click "Advanced system settings" or "System Properties".
  • Click the Advanced tab.
  • Click the "Environment Variables..." button.
  • Add the path(s) of the Flex and Bison programs to the PATH variable, under the system variables group box. Use the semi-colon (;) character to separate path items. (Example path to add: C:\gnuwin32\bin;
  • Press the OK button.
  • Press the OK button.
  • Either log off and log back on the computer, or restart it for the updated PATH to take effect.