From 6c969dce4a1487fee4b44e59514dbdb97a23360e Mon Sep 17 00:00:00 2001
From: Wenzel Jakob <wenzel@cs.cornell.edu>
Date: Sun, 30 Sep 2012 00:05:20 -0400
Subject: [PATCH] initial MLT documentation

---
 doc/main.bib                      | 11 +++++++
 src/integrators/mlt/mlt.cpp       | 52 ++++++++++++++++++++++++++-----
 src/integrators/pssmlt/pssmlt.cpp |  4 ++-
 3 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/doc/main.bib b/doc/main.bib
index 09ed83f4..74dcc1fc 100644
--- a/doc/main.bib
+++ b/doc/main.bib
@@ -247,6 +247,17 @@
 	year={1994}
 }
 
+@inproceedings{Veach1997Metropolis,
+	author = {Veach, Eric and Guibas, Leonidas J.},
+	title = {Metropolis light transport},
+	booktitle = {Proceedings of the 24th annual conference on Computer graphics and interactive techniques},
+	series = {SIGGRAPH '97},
+	year = {1997},
+	pages = {65--76},
+	publisher = {ACM Press/Addison-Wesley Publishing Co.},
+	address = {New York, NY, USA}
+}
+
 @article{Grunschloss2010Enumerating,
 	title={Enumerating Quasi-Monte Carlo Point Sequences in Elementary Intervals},
 	author={Gr{\"u}nschlo{\ss}, L. and Raab, M. and Keller, A.},
diff --git a/src/integrators/mlt/mlt.cpp b/src/integrators/mlt/mlt.cpp
index 2c7443f0..2087ca21 100644
--- a/src/integrators/mlt/mlt.cpp
+++ b/src/integrators/mlt/mlt.cpp
@@ -22,14 +22,50 @@
 
 MTS_NAMESPACE_BEGIN
 
-/**
+/*!\plugin{mlt}{Path Space Metropolis Light Transport}
  * \order{10}
- * Veach-style Metropolis Light Transport implementation with support for
- * bidirectional mutations, lens perturbations, caustic perturbations and 
- * multi-chain perturbations. Several optimizations are also implemented, 
- * namely separate direct illumination, two-stage MLT, 
- * and importance sampling of mutation strategies. For details, see the 
- * respective parameter descriptions.
+ * \parameters{
+ *	   \parameter{directSamples}{\Integer}{
+ *	       By default, this plugin renders the direct illumination component 
+ *	       separately using an optimized direct illumination sampling strategy 
+ *	       that uses low-discrepancy number sequences for superior performance
+ *	       (in other words, it is \emph{not} rendered by MLT). This
+ *	       parameter specifies the number of samples allocated to that method. To
+ *	       force PSSMLT to be responsible for the direct illumination
+ *	       component as well, set this parameter to \code{-1}. \default{16}
+ *	   }
+ *     \parameter{maxDepth}{\Integer}{Specifies the longest path depth
+ *         in the generated output image (where \code{-1} corresponds to $\infty$).
+ *	       A value of \code{1} will only render directly visible light sources.
+ *	       \code{2} will lead to single-bounce (direct-only) illumination, 
+ *	       and so on. \default{\code{-1}}
+ *	   }
+ *	   \parameter{rrDepth}{\Integer}{Specifies the minimum path depth, after 
+ *	      which the implementation will start to use the ``russian roulette'' 
+ *	      path termination criterion. \default{\code{5}}
+ *	   }
+ *	   \parameter{luminanceSamples}{\Integer}{
+ *	      MLT-type algorithms create output images that are only
+ *	      \emph{relative}. The algorithm can e.g. determine that a certain pixel
+ *	      is approximately twice as bright as another one, but the absolute
+ *	      scale is unknown. To recover it, this plugin computes
+ *	      the average luminance arriving at the sensor by generating a
+ *	      number of samples. \default{\code{100000} samples}
+ *     }
+ *     \parameter{twoStage}{\Boolean}{Use two-stage MLT?
+ *       See below for details. \default{{\footnotesize\code{false}}}}
+ *	   \parameter{\footnotesize bidirectional\showbreak Mutation, 
+ *	     [lens,caustic,multiChain,manifold]Perturbation, 
+ *	   causticPerturbation, multiChain\showbreak Perturbation, manifoldPerturbation}{\Boolean}{
+ *	     These parameters can be used to choose the mutation strategies that
+ *	     should be used. By default, only the bidirectional mutation is
+ *	     enabled.
+ *	   }
+ * }
+ * Metropolis Light Transport is a seminal rendering technique proposed by Veach and 
+ * Guibas \cite{Veach1997Metropolis}, which applies the Metropolis-Hastings
+ * algorithm to the problem of light transport in the path-space setting.
+ *
  */
 class MLT : public Integrator {
 public:
@@ -101,6 +137,8 @@ public:
 		/* Selectively enable/disable the manifold perturbation */ 
 		m_config.manifoldPerturbation = props.getBoolean("manifoldPerturbation", false);
 		m_config.probFactor = props.getFloat("probFactor", 50);
+
+		/* Stop MLT after X seconds -- useful for equal-time comparisons */
 		m_config.timeout = props.getInteger("timeout", 0);
 	}
 
diff --git a/src/integrators/pssmlt/pssmlt.cpp b/src/integrators/pssmlt/pssmlt.cpp
index da07747d..d25cafdf 100644
--- a/src/integrators/pssmlt/pssmlt.cpp
+++ b/src/integrators/pssmlt/pssmlt.cpp
@@ -225,7 +225,7 @@ public:
 		m_config.directSampling = props.getBoolean(
 				"directSampling", true);
 
-		/* Recommended mutation sizes in the primary sample space */
+		/* Recommended mutation sizes in primary sample space */
 		m_config.mutationSizeLow  = props.getFloat("mutationSizeLow",  1.0f/1024.0f);
 		m_config.mutationSizeHigh = props.getFloat("mutationSizeHigh", 1.0f/64.0f);
 		Assert(m_config.mutationSizeLow > 0 && m_config.mutationSizeHigh > 0 &&
@@ -241,6 +241,8 @@ public:
 		   possible, while ensuring that there are enough units to keep all 
 		   workers busy. */
 		m_config.workUnits = props.getInteger("workUnits", -1);
+
+		/* Stop MLT after X seconds -- useful for equal-time comparisons */
 		m_config.timeout = props.getInteger("timeout", 0);
 	}