333 lines
18 KiB
TeX
333 lines
18 KiB
TeX
\section{Compiling the renderer}
|
|
\label{sec:compiling}
|
|
To compile Mitsuba, you will need a recent C++ compiler (e.g. GCC 4.1+ or
|
|
Visual Studio 2008+) and some additional libraries, which Mitsuba uses internally.
|
|
Builds on all supported platforms are done using a unified system
|
|
based on SCons (\url{http://www.scons.org}), which is a Python-based
|
|
software construction tool. There are some differences between the different operating systems---for
|
|
more details, please refer to one of the next sections depending on which one you use.
|
|
|
|
\subsection{Common steps}
|
|
To get started, you will need to download a recent version of Mitsuba. Make sure that you have the Mercurial (\url{http://mercurial.selenic.com/}) versioning system installed\footnote{On Windows, you might also want the convenient TortoiseHG shell extension (\url{http://tortoisehg.bitbucket.org/}) to run the subsequent steps directly from the Explorer.} and enter the following at the command prompt:
|
|
\begin{shell}
|
|
$\texttt{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba
|
|
\end{shell}
|
|
Afterwards, you will need to download the precompiled dependencies into a new
|
|
subdirectory named \code{mitsuba/dependencies}:
|
|
\begin{shell}
|
|
$\texttt{\$}$ cd mitsuba
|
|
$\texttt{\$}$ hg clone https://www.mitsuba-renderer.org/hg/dependencies
|
|
\end{shell}
|
|
Common to all platforms is that a build configuration file must be chosen: amongst the
|
|
following, please copy the best matching file into a new file to the root of the Mitsuba
|
|
directory and rename it into \code{config.py}.
|
|
\begin{shell}
|
|
build/config-linux.py
|
|
build/config-darwin-x86_64.py
|
|
build/config-darwin-x86.py
|
|
build/config-darwin-universal.py
|
|
build/config-msvc2008-win32.py
|
|
build/config-msvc2008-win64.py
|
|
build/config-msvc2010-win32.py
|
|
build/config-msvc2010-win64.py
|
|
build/config-icl12-msvc2010-win32.py
|
|
build/config-icl12-msvc2010-win64.py
|
|
\end{shell}
|
|
|
|
\subsection{Compilation flags}
|
|
\label{sec:compiling-flags}
|
|
Usually, you will not have to make any modification to this file, but sometimes a few minor
|
|
edits may be necessary. In particular, you might want to add or remove certain
|
|
compilation flags from the \code{CXXFLAGS} parameter. The following settings
|
|
affect the behavior of Mitsuba:
|
|
\begin{description}
|
|
\item[\texttt{MTS\_DEBUG}] Enable assertions etc. Usually a good idea, and
|
|
enabled by default.
|
|
\item[\texttt{MTS\_KD\_DEBUG}] Enable additional checks in the kd-Tree. This
|
|
is quite slow and mainly useful to track down bugs when they are suspected.
|
|
\item[\texttt{MTS\_KD\_CONSERVE\_MEMORY}] Use a more compact representation
|
|
for triangle geometry (at the cost of speed). This flag causes Mitsuba to use the somewhat slower
|
|
Moeller-Trumbore triangle intersection method instead of the default Wald
|
|
intersection test, which has an overhead of 48 bytes per triangle.
|
|
Off by default.
|
|
\item[\texttt{MTS\_SSE}]Activate optimized SSE routines. On by default.
|
|
\item[\texttt{MTS\_HAS\_COHERENT\_RT}]Include coherent ray tracing support (depends on \texttt{MTS\_SSE}). This flag is activated by default.
|
|
\item[\texttt{MTS\_DEBUG\_FP}]Generated NaNs and overflows will cause floating point exceptions, which can be caught in a debugger. This is slow and mainly meant as a debugging tool for developers. Off by default.
|
|
\item[\texttt{SPECTRUM\_SAMPLES=}$\langle ..\rangle$]This setting defines the number of spectral samples (in the 368-830 $nm$ range) that are used to render scenes. The default is 3 samples, in which case the renderer automatically turns into an RGB-based system. For high-quality spectral rendering, this should be set to 30 or higher.
|
|
\item[\texttt{SINGLE\_PRECISION}] Do all computation in single precision. This is normally sufficient and therefore used as the default setting.
|
|
\item[\texttt{DOUBLE\_PRECISION}] Do all computation in double precision. This flag is incompatible with
|
|
\texttt{MTS\_SSE}, \texttt{MTS\_HAS\_COHERENT\_RT}, and \texttt{MTS\_DEBUG\_FP}.
|
|
\item[\texttt{MTS\_GUI\_SOFTWARE\_FALLBACK}]Forces the GUI to use a software
|
|
fallback mode, which is considerably slower and removes the realtime preview.
|
|
This is useful when running the interface on a remote Windows machine
|
|
accessed via the Remote Desktop Protocol (RDP).
|
|
\end{description}
|
|
All of the default configurations files located in the \texttt{build} directory use the flags
|
|
\code{SINGLE\_PRECISION}, \code{SPECTRUM\_SAMPLES=3}, \code{MTS\_DEBUG}, \code{MTS\_SSE},
|
|
as well as \code{MTS\_HAS\_COHERENT\_RT}.
|
|
|
|
\subsection{Building on Ubuntu Linux}
|
|
\label{sec:compiling-ubuntu}
|
|
You'll first need to install a number of dependencies. It is assumed here
|
|
that you are using Ubuntu Linux (Maverick Meerkat / 10.10 or later), hence some of the package may be named differently if you are
|
|
using another version.
|
|
|
|
First, run
|
|
\begin{shell}
|
|
$\text{\$}$ sudo apt-get install build-essential scons mercurial qt4-dev-tools libpng12-dev
|
|
libjpeg62-dev libilmbase-dev libxerces-c3-dev libboost1.42-all-dev
|
|
libopenexr-dev libglewmx1.5-dev libxxf86vm-dev libpcrecpp0
|
|
libboost-system-dev libboost-filesystem-dev libboost-python-dev libboost-dev
|
|
\end{shell}
|
|
Please ensure that the installed version of the boost libraries is 1.42 or later.
|
|
To get COLLADA support, you will also need to install the \texttt{collada-dom} packages or build it from scratch. Here, we install the \code{x86\_64} binaries and development headers that can be found in the \texttt{dependencies/linux} directory\footnote{The directory also contains source packages in case these binaries don't work for you.}:
|
|
\begin{shell}
|
|
$\text{\$}$ sudo dpkg --install collada-dom_2.3.1-1_amd64.deb collada-dom-dev_2.3.1-1_amd64.deb
|
|
\end{shell}
|
|
Afterwards, simply run
|
|
\begin{shell}
|
|
$\text{\$}$ scons
|
|
\end{shell}
|
|
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the build by appending \code{-j }\emph{core count} to the command.
|
|
If all goes well, SCons should finish successfully within a few minutes:
|
|
\begin{shell}
|
|
scons: $\texttt{done}$ building targets.
|
|
\end{shell}
|
|
To be able to run the renderer from the command line, you will also have to import it into your path:
|
|
\begin{shell}
|
|
$\text{\$}$ . setpath.sh
|
|
\end{shell}
|
|
(note the period at the beginning -- this assumes that you are using \code{bash}).
|
|
Having set up everything, you can now move on to \secref{basics}.
|
|
\subsubsection{Creating Ubuntu packages}
|
|
For Ubuntu, the preferred way of redistristributing executables is to create
|
|
\code{.deb} package files. To create Mitsuba packages, it is strongly recommended
|
|
that you work with a pristine Ubuntu installation\footnote{Several commercial graphics
|
|
drivers ``pollute'' the OpenGL setup so that the compiled Mitsuba binaries
|
|
can only be used on machines using the same drivers. For this reason, it is
|
|
better to work from a clean boostrapped install.}. This can be done as follows:
|
|
first, install \code{debootstrap} and download the latest version of Ubuntu
|
|
to a subdirectory (here, we use Maverick Meerkat, or version 10.10)
|
|
\begin{shell}
|
|
$\text{\$}$ sudo apt-get install debootstrap
|
|
$\text{\$}$ sudo debootstrap --arch amd64 maverick maverick-pristine
|
|
\end{shell}
|
|
Next, \code{chroot} into the created directory, enable the \code{multiverse} package repository,
|
|
and install the necessary tools for creating package files:
|
|
\begin{shell}
|
|
$\text{\$}$ sudo chroot maverick-pristine
|
|
$\text{\$}$ echo "deb http://archive.ubuntu.com/ubuntu maverick universe" >> /etc/apt/sources.list
|
|
$\text{\$}$ apt-get update
|
|
$\text{\$}$ apt-get install debhelper dpkg-dev pkg-config
|
|
\end{shell}
|
|
Now, you should be able to set up the remaining dependencies as described in \secref{compiling-ubuntu}.
|
|
Once this is done, check out a copy of Mitsuba to the root directory of the \code{chroot} environment, e.g.
|
|
\begin{shell}
|
|
$\text{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba
|
|
\end{shell}
|
|
To start the compilation process, enter
|
|
\begin{shell}
|
|
$\text{\$}$ cd mitsuba
|
|
$\text{\$}$ cp -R data/linux/debian debian
|
|
$\text{\$}$ dpkg-buildpackage -nc
|
|
\end{shell}
|
|
After everything has been built, you should find the created package files
|
|
in the root directory.
|
|
\subsubsection{Releasing Ubuntu packages}
|
|
To redistribute Ubuntu packages over the Internet, it is convenient to
|
|
put them into an \code{apt}-compatible repository. To prepare such a
|
|
repository, put the two \code{deb}-files built in the last section,
|
|
as well as the \code{collada-dom} \code{deb}-files into a public directory
|
|
made available by a HTTP server and inside it, run
|
|
\begin{shell}
|
|
$path-to-htdocs\text{\$}$ dpkg-scanpackages path/to/deb-directory /dev/null | gzip -9c > path/to/deb-directory/Packages.gz
|
|
\end{shell}
|
|
This will create a respository index file named \code{Packages.gz}.
|
|
Note that you must execute this command in the root directory of the
|
|
HTTP server's web directory and provide the relative path to the
|
|
package files -- otherwise, the index file will specify the wrong package
|
|
paths. Finally, the whole directory can be uploaded to some public location
|
|
and then referenced by placing a line following the pattern
|
|
\begin{shell}
|
|
deb http://<path-to-deb-directory> ./
|
|
\end{shell}
|
|
into the \code{/etc/apt/sources.list} file.
|
|
|
|
\subsection{Building on Fedora Core}
|
|
You'll first need to install a number of dependencies. It is assumed here
|
|
that you are using FC15, hence some of the package may be named differently if you are
|
|
using another version.
|
|
|
|
First, run
|
|
\begin{shell}
|
|
$\text{\$}$ yum install mercurial gcc-c++ scons boost-devel qt4-devel OpenEXR-devel xerces-c-devel python-devel glew-devel collada-dom-devel
|
|
\end{shell}
|
|
Afterwards, simply run
|
|
\begin{shell}
|
|
$\text{\$}$ scons
|
|
\end{shell}
|
|
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the build by appending \code{-j }\emph{core count} to the command.
|
|
If all goes well, SCons should finish successfully within a few minutes:
|
|
\begin{shell}
|
|
scons: $\texttt{done}$ building targets.
|
|
\end{shell}
|
|
To be able to run the renderer from the command line, you will also have to import it into your path:
|
|
\begin{shell}
|
|
$\text{\$}$ . setpath.sh
|
|
\end{shell}
|
|
(note the period at the beginning -- this assumes that you are using \code{bash}).
|
|
Having set up everything, you can now move on to \secref{basics}.
|
|
\subsubsection{Creating Fedora Core packages}
|
|
To create \code{RPM} packages, you will need to install the \code{RPM} development tools:
|
|
\begin{shell}
|
|
$\text{\$}$ yum install rpmdevtools
|
|
\end{shell}
|
|
Once this is done, run the following command in your home directory:
|
|
\begin{shell}
|
|
$\text{\$}$ rpmdev-setuptree
|
|
\end{shell}
|
|
and create a Mitsuba source package in the appropriate directory:
|
|
\begin{shell}
|
|
$\text{\$}$ ln -s mitsuba mitsuba-$\code{\MitsubaVersion}$
|
|
$\text{\$}$ tar czvf rpmbuild/SOURCES/mitsuba-$\code{\MitsubaVersion}$.tar.gz mitsuba-$\code{\MitsubaVersion}$/.
|
|
\end{shell}
|
|
Finally, \code{rpmbuilder} can be invoked to create the package:
|
|
\begin{shell}
|
|
$\text{\$}$ rpmbuild -bb mitsuba-$\code{\MitsubaVersion}$/data/linux/fedora/mitsuba.spec
|
|
\end{shell}
|
|
After this command finishes, its output can be found in the directory \code{rpmbuild/RPMS}.
|
|
\subsection{Building on Arch Linux}
|
|
There are two ways to install Mitsuba on Archlinux, the Arch way, and the other way.
|
|
|
|
The Arch Way is to use the Aur software repository.
|
|
Accessing software in the Aur repository is easiest when using a script called \texttt{packer}.
|
|
|
|
First download packer then use \texttt{makepkg} to build and install it.
|
|
The \texttt{-is} flags will prompt you for your sudo password and then install the package after it has finished building as well as install any needed dependencies.
|
|
\begin{shell}
|
|
$\text{\$}$ mkdir packer && cd packer
|
|
$\text{\$}$ wget http://aur.archlinux.org/packages/packer/packer/PKGBUILD
|
|
$\text{\$}$ makepkg -is
|
|
\end{shell}
|
|
|
|
Next, use packer to automatically download, build, and install Mitsuba as well as any needed dependencies.
|
|
The optional \code{--noedit} flag is used if you do not wish to edit the files after they are downloaded.
|
|
The optional \code{--noconfirm} flag is used if you do not wish to confirm each step of the installation.
|
|
\begin{shell}
|
|
$\text{\$}$ sudo packer -S --noedit --noconfirm mitsuba-hg glewmx collada-dom
|
|
\end{shell}
|
|
|
|
Periodically you may wish to update Mitsuba to the latest version.
|
|
To do this simply reinstall it and packer will pull and build the latest version.
|
|
\begin{shell}
|
|
$\text{\$}$ sudo packer -S --noedit --noconfirm mitsuba-hg
|
|
\end{shell}
|
|
|
|
Alternatively you can skip using packer and manually download the files and install them one at a time yourself.
|
|
First install glewmx
|
|
\begin{shell}
|
|
$\text{\$}$ mkdir glewmx && cd glewmx
|
|
$\text{\$}$ wget http://aur.archlinux.org/packages/glewmx/glewmx/PKGBUILD
|
|
$\text{\$}$ makepkg -is
|
|
\end{shell}
|
|
|
|
And then collada-dom
|
|
\begin{shell}
|
|
$\text{\$}$ mkdir collada-dom && cd collada-dom
|
|
$\text{\$}$ wget http://aur.archlinux.org/packages/collada-dom/collada-dom/PKGBUILD
|
|
$\text{\$}$ makepkg -is
|
|
\end{shell}
|
|
|
|
And finally Mitsuba
|
|
\begin{shell}
|
|
$\text{\$}$ mkdir mitsuba-hg && cd mitsuba-hg
|
|
$\text{\$}$ wget http://aur.archlinux.org/packages/mitsuba-hg/mitsuba-hg/PKGBUILD
|
|
$\text{\$}$ makepkg -is
|
|
\end{shell}
|
|
|
|
To uninstall do this
|
|
\begin{shell}
|
|
$\text{\$}$ sudo pacman -R mitsuba-hg glewmx collada-dom
|
|
\end{shell}
|
|
After installing you will be able to run the renderer from the command line.
|
|
Having set up everything, you can now move on to \secref{basics}.
|
|
|
|
If for some reason you are unable access the Aur files, they are also hosted at
|
|
(\url{https://www.mitsuba-renderer.org/releases/contrib/archlinux/}).
|
|
|
|
\subsection{Building on Windows}
|
|
On the Windows platform, Mitsuba already includes most of the dependencies in precompiled form.
|
|
You will still need to set up a few things though: first, you need to install Python
|
|
(\url{www.python.org}) and SCons\footnote{Note that on some Windows machines, the SCons
|
|
installer generates a warning about not finding Python in the registry. In this case, you can instead run \code{python setup.py install} within the source release of SCons.} (\url{http://www.scons.org}) and ensure that they are contained in the \code{\%PATH\%} environment variable so that entering \code{scons} on the command prompt (\code{cmd.exe}) launches the build system.
|
|
|
|
Next, you will either need to compile Qt 4.7 (or a newer version) from
|
|
source or grab pre-built binaries (e.g. from
|
|
\url{http://code.google.com/p/qt-msvc-installer}).
|
|
It is crucial that the Qt build configuration \emph{exactly} matches that of Mitsuba:
|
|
for instance, if you were planning to use the 64-bit compiler in Visual
|
|
Studio 2010, both projects must be built with that exact same compiler.
|
|
|
|
When building Qt from source, an important point is to install any
|
|
Visual Studio service packs prior to this step---for instance, 64-bit
|
|
Qt binaries always crash when built with a Visual Studio 2010 installation
|
|
that is missing SP1. Once that is take care of, start the correct Visual Studio command
|
|
prompt, and enter
|
|
\begin{shell}
|
|
C:\Qt>configure.exe -release -no-webkit -no-phonon -no-phonon-backend -no-script
|
|
-no-scripttools -no-qt3support -no-multimedia -no-ltcg
|
|
..(configuration messages)..
|
|
C:\Qt>nmake
|
|
\end{shell}
|
|
inside the Qt directory.
|
|
|
|
Having installed all dependencies, run the ``Visual Studio \emph{2008/2010} Command
|
|
Prompt'' from the Start Menu (\code{x86} for 32-bit or \code{x64} for 64bit). Afterwards,
|
|
navigate to the Mitsuba directory.
|
|
Depending on whether or not the Qt binaries are on the \code{\%PATH\%}
|
|
environment variable, you might have to explicitly specify the Qt path:
|
|
\begin{shell}
|
|
C:\Mitsuba\>$\texttt{set}$ QTDIR=C:\Qt
|
|
\end{shell}
|
|
where \code{C:$\backslash$Qt} is the path to your Qt installation.
|
|
Afterwards, simply run
|
|
\begin{shell}
|
|
C:\Mitsuba\>scons
|
|
\end{shell}
|
|
In the case that you have multiple processors, you might want to parallelize the build by appending the option \code{-j }\emph{core count} to the \code{scons} command.
|
|
|
|
If all goes well, the build process will finish successfully after a few
|
|
minutes. In comparison to the other platforms, you don't have to run the \code{setpath.sh} script at this point.
|
|
All binaries are now located in the \code{dist} directory, and they should be executed directly from there.
|
|
|
|
\subsubsection{Integration with the Visual Studio interface}
|
|
Basic Visual Studio 2008 and 2010 integration with support for code completion
|
|
exists for those who develop Mitsuba code on Windows.
|
|
To use the supplied projects, simply double-click on one of the two files \code{build/mitsuba-msvc2008.sln}
|
|
and \code{build/mitsuba-msvc2010.sln}. These Visual Studio projects still internally
|
|
use the SCons-based build system to compile Mitsuba; whatever
|
|
build configuration is selected within Visual Studio will be used to pick a matching
|
|
configuration file from the \texttt{build} directory. Note that you will
|
|
potentially have to add a \code{QTDIR=\"...\"} line to each of the
|
|
used configuration files when building directly from Visual Studio.
|
|
|
|
\subsection{Building on Mac OS X}
|
|
On Mac OS X, you will need to install both scons (\code{www.scons.org}) and
|
|
a recent release of XCode. You will also need to get Qt 4.7.0 or a newer version
|
|
--- make sure that you get the normal Cocoa release (i.e. \emph{not} the one based on Carbon). All of the
|
|
other dependencies are already included in precompiled form.
|
|
Now open a Terminal and run
|
|
\begin{shell}
|
|
$\text{\$}$ scons
|
|
\end{shell}
|
|
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the build by appending \code{-j }\emph{core count} to the command.
|
|
If all goes well, SCons should finish successfully within a few minutes:
|
|
\begin{shell}
|
|
scons: $\texttt{done}$ building targets.
|
|
\end{shell}
|
|
To be able to run the renderer from the command line, you will have to import it into your path:
|
|
\begin{shell}
|
|
$\text{\$}$ . setpath.sh
|
|
\end{shell}
|
|
(note the period at the beginning -- this assumes that you are using \code{bash}).
|