merged with main branch

README

@@ -188,7 +188,7 @@ Network rendering:
 	entails installing a suitable "~/.ssh/authorized_keys2" file on the server
 	and running "ssh-agent" on the client. On Windows, the situation is a bit
 	more complicated because it does not come with a suitable SSH client by
-	default. To get SSH to work, biquaque requires plink.exe (from PUTTY) to
+	default. To get SSH to work, Mitsuba requires plink.exe (from PUTTY) to
 	be on the $PATH. For passwordless authentication with a Linux/OSX-based
 	server, convert your private key to PuTTY's format (with the help 
 	of puttygen.exe). Afterwards, pageant.exe is required to load and 

SConstruct

@@ -136,8 +136,8 @@ if not conf.CheckCHeader(['stdio.h', 'jpeglib.h']):
 if not conf.CheckCXXHeader('ImfRgba.h'):
 	print 'OpenEXR is missing (install libopenexr-dev)'
 	Exit(1)
-if not conf.CheckCXXHeader('xercesc/util/PlatformUtils.hpp'):
+if not conf.CheckCXXHeader('xercesc/dom/DOMLSParser.hpp'):
-	print 'Xerces-C must be installed (install libxerces-c2-dev)!'
+	print 'Xerces-C++ 3.x must be installed (install libxerces-c-dev)!'
 	Exit(1)
 if not conf.CheckCXXHeader('dae.h'):
 	hasCollada = False
@@ -379,6 +379,7 @@ shandler = mainEnv.StaticObject('src/mitsuba/shandler.cpp')
 # Build the command-line+GUI interface
 mainEnv.Program('mtssrv', resources + ['src/mitsuba/mtssrv.cpp'])
 mainEnv.Program('mitsuba', resources + ['src/mitsuba/mitsuba.cpp', shandler])
+mainEnv.Program('mtsutil', resources + ['src/mitsuba/mtsutil.cpp', shandler])
 
 if sys.platform == 'darwin':
 	mainEnv_osx = mainEnv.Clone();
@@ -389,7 +390,6 @@ if sys.platform == 'darwin':
 
 env.Program('src/utils/utils_test', ['src/utils/utils_test.cpp'])
 env.Program('src/utils/joinrgb', ['src/utils/joinrgb.cpp'])
-env.Program('src/utils/addimages', ['src/utils/addimages.cpp'])
 env.Program('src/utils/ssalbedo', ['src/utils/ssalbedo.cpp'])
 env.Program('src/utils/dumpimage', ['src/utils/dumpimage.cpp'])
 env.Program('src/utils/ttest', ['src/utils/ttest.cpp'])
@@ -458,7 +458,10 @@ if hasQt:
 
 plugins = []
 
-# Build the plugins -- BSDFs
+# Build the plugins -- Utilities
+plugins += env.SharedLibrary('plugins/addimages', ['src/utils/addimages.cpp'])
+
+# BSDFs
 plugins += env.SharedLibrary('plugins/lambertian', ['src/bsdfs/lambertian.cpp'])
 plugins += env.SharedLibrary('plugins/dielectric', ['src/bsdfs/dielectric.cpp'])
 plugins += env.SharedLibrary('plugins/mirror', ['src/bsdfs/mirror.cpp'])
@@ -470,6 +473,7 @@ plugins += env.SharedLibrary('plugins/roughglass', ['src/bsdfs/roughglass.cpp'])
 plugins += env.SharedLibrary('plugins/roughmetal', ['src/bsdfs/roughmetal.cpp'])
 plugins += env.SharedLibrary('plugins/composite', ['src/bsdfs/composite.cpp'])
 
+
 # Phase functions
 plugins += env.SharedLibrary('plugins/isotropic', ['src/phase/isotropic.cpp'])
 plugins += env.SharedLibrary('plugins/hg', ['src/phase/hg.cpp'])
@@ -610,6 +614,7 @@ if sys.platform == 'win32':
 		dllprefix='tools/windows/lib32/'
 	installTargets += env.Install('dist', 'mitsuba.exe')
 	installTargets += env.Install('dist', 'mtssrv.exe')
+	installTargets += env.Install('dist', 'mtsutil.exe')
 	installTargets += env.Install('dist', 'mtsimport.exe')
 	installTargets += env.Install('dist', 'mtsgui.exe')
 	installTargets += env.Install('dist', 'src/libcore/libcore.dll')
@@ -649,6 +654,7 @@ elif sys.platform == 'darwin':
 		installTargets += env.Install('Mitsuba.app/plugins', i)
 	installTargets += env.Install('Mitsuba.app/schema', 'schema/scene.xsd')
 	installTargets += env.Install('Mitsuba.app/Contents/MacOS', 'mtssrv')
+	installTargets += env.Install('Mitsuba.app/Contents/MacOS', 'mtsutil')
 	installTargets += env.Install('Mitsuba.app/Contents/MacOS', 'mitsuba')
 	installTargets += env.Install('Mitsuba.app/Contents/MacOS', 'mtsimport')
 	plist = env.Install('Mitsuba.app/Contents', 'tools/darwin/Info.plist')

doc/Makefile

@@ -1,2 +1,2 @@
-main.pdf: main.tex introduction.tex compiling.tex basics.tex format.tex integrator.tex acknowledgements.tex
+main.pdf: main.tex introduction.tex compiling.tex basics.tex format.tex import.tex integrator.tex parallelization.tex acknowledgements.tex
 	pdflatex main.tex

doc/basics.tex

@@ -8,6 +8,7 @@ To launch the interactive frontend, run \code{Mitsuba.app} on MacOS,
 You can also drag and drop scene files onto the application icon or the running program to open them.
 A quick video tutorial on using the GUI can be found here: \url{http://vimeo.com/13480342}.
 \subsection{Command line interface}
+\label{sec:mitsuba}
 The \texttt{mitsuba} binary is an alternative non-interactive rendering 
 frontend for command-line use and batch job operation.
 To get a listing of the parameters it supports, run
@@ -186,3 +187,52 @@ Options/Arguments:
 
  The README file included with the distribution contains further information.
 \end{console}
+\subsection{Direct connection server}
+A Mitsuba compute node can be created using the \code{mtssrv} executable. By default,
+it will listen on port 7554:
+\begin{shell}
+$\texttt{\$}$ mtssrv
+..
+maxwell: Listening on port 7554.. Send Ctrl-C or SIGTERM to stop.
+\end{shell}
+Type \code{mtssrv -h} to see a list of available options.
+If you find yourself unable to connect to the server, \code{mtssrv} is probably listening on
+the wrong interface. In this case, please specify an explicit IP address or hostname:
+\begin{shell}
+$\texttt{\$}$ mtssrv -i maxwell.cs.cornell.edu
+\end{shell}
+As advised in Section~\ref{sec:mitsuba}, it is advised to run \code{mtssrv} \emph{only} in trusted networks.
+
+One nice feature of \code{mtssrv} is that it (like \code{mitsuba}) also supports the \code{-c} and \code{-s} 
+parameters, which can be used to connect to additional compute servers. 
+This allows building large hierarchies of nodes,
+where communication occurs only amongst neighbors and the root node presents itself as
+a computer with hundreds of cores.
+Connecting clients will not be able to distinguish additional cores obtained in this manner  
+from the actual server cores. 
+
+Such hierarchies are mainly useful to reduce communication bottlenecks when distributing
+large resources (such as scenes) to remote machines. Imagine the following hypothetical scenario:
+you would like to render a 50MB-sized scene while at home, but rendering is too slow. 
+You decide to tap into some extra machines available
+at your workplace, but this usually doesn't make things much faster because of the relatively slow broadband
+connection and the need to transmit your scene to every single compute node involved. 
+
+Using \code{mtssrv}, you can
+instead designate a central scheduling node at your workplace, which accepts connections and delegates
+rendering tasks to the other machines. In this case, you will only have to transmit the scene once,
+and the remaining distribution happens over the comparatively fast ethernet at your workplace.
+\subsection{Utility launcher}
+\label{sec:mtsutil}
+When working on a larger project, one often needs to implement various utility programs that 
+perform simple tasks, such as applying a filter to an image or processing
+a matrix stored in a file. In a framework like Mitsuba, this unfortunately involves 
+a significant coding overhead in initializing the necessary APIs on all supported platforms. 
+To reduce this tedious work on the side of the programmer, Mitsuba comes with a utility launcher
+called \code{mtsutil}.
+
+The general usage of this command is
+\begin{shell}
+$\texttt{\$}$ mtsutil [options] <utility name> [arguments]
+\end{shell}
+For a listing of all supported options and utilities, enter the command without parameters.

doc/main.tex

@@ -112,6 +112,7 @@
 \include{basics}
 \include{format}
 \include{plugins}
+\include{import}
 \include{integrator}
 \include{parallelization}
 \include{acknowledgements}

doc/parallelization.tex

@@ -1,2 +1,27 @@
 \section{Parallelization layer}
-TBD
+Mitsuba is built on top of a flexible parallelization layer, which can spread out
+various types of computation over local and remote cores.
+The guiding principle is that if an operation can potentially take longer than a
+few seconds, it ought to use all the cores it can get.
+
+Here, we will go through a simple example, which will hopefully provide sufficient intuition
+to realize more complex tasks. 
+To obtain good (i.e. close to linear) speedups, the parallelization layer depends on
+several key assumptions of the task to be parallelized:
+\begin{itemize}
+\item The task can easily be split up into a discrete number of work units, which requires a negligible amount of computation.
+\item Each work unit is small in footprint so that it can easily be transferred over the network or shared memory. 
+\item A work unit constitutes a significant amount of computation, which by far outweighs the cost of transmitting it to another node.
+\item The `work result' obtained by processing a work unit is again small in footprint, so that it can easily be transferred back.
+\item Merging all `work results' to a solution of the whole problem requires a negligible amount of additional computation.
+\end{itemize}
+This essentially corresponds to a parallel version of \emph{Map} (as in \emph{Map\&Reduce}), which is very
+well-suited for many rendering workloads. 
+
+The example we consider here computes a \code{ROT13} ``encryption'' of a string, which 
+most certainly violates the `significant amount of computation' assumption. Nevertheless, 
+the inherent parallelism and simplicity of this task make it a good example.
+
+All of the relevant interfaces are contained in \code{include/mitsuba/core/sched.h}.
+
+

include/mitsuba/render/records.h

@@ -74,7 +74,7 @@ public:
 	 * Should only be called if the intersected
 	 * shape does indeed have a subsurface integrator!
 	 */
-	inline Spectrum LoSub(const Vector &d) const;
+	inline Spectrum LoSub(const Scene *scene, const Vector &d) const;
 
 	/// Computes texture coordinate partials
 	void computePartials(const RayDifferential &ray);

include/mitsuba/render/records.inl

@@ -15,8 +15,8 @@ inline Spectrum Intersection::Le(const Vector &d) const {
 		LuminaireSamplingRecord(*this, d));
 }
 
-inline Spectrum Intersection::LoSub(const Vector &d) const {
+inline Spectrum Intersection::LoSub(const Scene *scene, const Vector &d) const {
-	return shape->getSubsurface()->Lo(*this, d);
+	return shape->getSubsurface()->Lo(scene, *this, d);
 }
 	
 inline const BSDF *Intersection::getBSDF(const RayDifferential &ray) {

include/mitsuba/render/subsurface.h

@@ -28,14 +28,7 @@ public:
 	inline const std::vector<Shape *> getShapes() const { return m_shapes; }
 
 	/// Get the exitant radiance for a point on the surface
-	virtual Spectrum Lo(const Intersection &its,
+	virtual Spectrum Lo(const Scene *scene, const Intersection &its, const Vector &d) const = 0;
-		const Vector &d) const = 0;
-	
-	/**
-	 * Query the the readiance function inside the object. Requires a surface
-	 * normal used to create a slab approximation
-	 */
-	virtual Spectrum Li(const Ray &ray, const Normal &n) const = 0;
 
 	/// Serialize this subsurface integrator to a binary data stream
 	void serialize(Stream *stream, InstanceManager *manager) const;

src/bsdfs/microfacet.cpp

@@ -260,7 +260,7 @@ public:
 
 	std::string toString() const {
 		std::ostringstream oss;
-		oss << "Microfacet["
+		oss << "Microfacet[" << endl
 			<< "  diffuseReflectance = " << indent(m_diffuseReflectance->toString()) << "," << endl
 			<< "  specularReflectance = " << indent(m_specularReflectance->toString()) << "," << endl
 			<< "  intIOR = " << m_intIOR << "," << endl