documentation of the lambertian plugin

doc/basics.tex

@@ -16,7 +16,7 @@ the executable without parameters:
 \begin{shell}
 $\texttt{\$}$ mitsuba
 \end{shell}
-\clst{mitsuba-cli} shows the output resulting from this command. The most common
+\lstref{mitsuba-cli} shows the output resulting from this command. The most common
 mode of operation is to render a single scene, which is provided as a parameter, e.g.
 \begin{shell}
 $\texttt{\$}$ mitsuba path-to/my-scene.xml

doc/gendoc.py

@@ -10,7 +10,7 @@ def process(target, filename):
 	f = open(filename)
 	inheader = False
 	for line in f.readlines():
-		match = re.match(r'^/\*!(.*)$', line)
+		match = re.match(r'^/\*! ?(.*)$', line)
 		if match != None:
 			print("Processing %s" % filename)
 			line = match.group(1).replace('%', '\%')
@@ -22,7 +22,7 @@ def process(target, filename):
 		if re.search(r'^[\s\*]*\*/$', line):
 			inheader = False
 			continue
-		match = re.match(r'^\s*\**(.*)$', line)
+		match = re.match(r'^\s*\** ?(.*)$', line)
 		if match != None:
 			line = match.group(1).replace('%', '\%')
 			target.write(line + '\n')
@@ -43,6 +43,7 @@ def traverse(target, dirname, files):
 os.chdir(os.path.dirname(__file__))
 f = open('plugins_generated.tex', 'w')
 f.write('\section{Plugin reference}\n')
-os.path.walk('../src', traverse, f)
+f.write('\input{section_bsdf}\n')
+os.path.walk('../src/bsdfs', traverse, f)
 f.close()
 os.system('pdflatex main.tex')

doc/images/mitsuba.feynman.log

@@ -0,0 +1 @@
+2011-06-25 14:41:06 INFO  main [build/release/qtgui/mainwindow.cpp:75] Mitsuba version 0.2.1, Copyright (c) 2011 Wenzel Jakob

doc/main.tex

@@ -15,29 +15,32 @@
 \usepackage{listings}
 \usepackage{amsmath}
 \usepackage{enumerate}
+\usepackage{calc}
 \usepackage[utf8]{inputenc}
 
-\setcounter{tocdepth}{2}
+\setcounter{secnumdepth}{3}
+\setcounter{tocdepth}{3}
+
+\newcommand{\MitsubaVersion}{0.2.1}
 
 \usepackage[
-	bookmarks
-	,bookmarksnumbered
-	,colorlinks
-	,linkcolor=myblue
-	,urlcolor=myblue
-	,citecolor=myblue
-	,pdfpagelabels
-	,pdftitle={Mitsuba documentation}
-	,pdfauthor={Wenzel Jakob}
-	,pdfstartview=FitH
+	bookmarks,
+	bookmarksnumbered,
+	colorlinks,
+	linkcolor=myblue,
+	urlcolor=myblue,
+	citecolor=myblue,
+	pdfpagelabels,
+	pdftitle={Mitsuba \MitsubaVersion\, Documentation},
+	pdfauthor={Wenzel Jakob},
+	pdfstartview=FitH
 ]{hyperref}
 
 \typearea[current]{last}
 \raggedbottom
 
 \usepackage[expansion=false]{microtype}
-%\UseMicrotypeSet[protrusion]{basictext}
-
+\UseMicrotypeSet[protrusion]{basictext}
 \renewcommand*\ttdefault{txtt}
 
 \usepackage{scrpage2}
@@ -58,39 +61,60 @@
 \definecolor{lstshade}{gray}{0.94}
 \definecolor{lstframe}{gray}{0.75}
 \definecolor{lstcomment}{gray}{0.5}
+\definecolor{lstattrib}{rgb}{0,0.25,0}
 
 % Cite a figure/listing
-\newcommand{\cfig}[1]{\mbox{Figure \ref{fig:#1}}}
-\newcommand{\clst}[1]{\mbox{Listing \ref{lst:#1}}}
+\renewcommand{\lstlistingname}{Listing}
+\newcommand{\figref}[1]{\mbox{Figure \ref{fig:#1}}}
+\newcommand{\lstref}[1]{\mbox{Listing \ref{lst:#1}}}
 \newcommand{\code}[1]{\texttt{#1}}
 
 % Macros for plugin documentation
-\newcommand{\plugin}[2]{\subsection{#2 (\texttt{#1})}\label{plg:#1}}
+\newcommand{\plugin}[2]{\subsubsection{#2 (\texttt{#1})}\label{plg:#1}}
 \newcommand{\pluginref}[1]{\texttt{\hyperref[plg:#1]{#1}}}
 
+
 % Listings settings
 \lstset{
 	mathescape = true,
-	captionpos = b,
-	frame = single,
+	frame = lrtb,
 	backgroundcolor = \color{lstshade},
 	rulecolor = \color{lstframe},
 	tabsize = 4,
 	columns = flexible,
 	keepspaces,
 	belowskip = \smallskipamount,
-	keywordstyle = \bfseries,
-	commentstyle=\color{lstcomment}\itshape,
-	basicstyle = \small\ttfamily,
+	framerule = .7pt,
+	basicstyle = \small\ttfamily\raggedright,
 	breaklines = true,
-	showstringspaces = false
+	showstringspaces = false,
+	keywordstyle = \bfseries,
+	captionpos = b,
+	upquote = true
 }
 
-\lstnewenvironment{cpp}{\lstset{language=c++}}
+
+\lstdefinelanguage{xml} {
+	sensitive=true,
+	morecomment=[s][\color{lstcomment}\itshape]{<!--}{-->},
+	morecomment=[s][\color{lstcomment}]{<?}{?>},
+	string=[b]", stringstyle=\color{lstattrib},
+	keywords= [1] {
+		shape,bsdf,scene,texture,phase,integer,float,
+		string,transform,ref,rgb,srgb,spectrum,blackbody,
+		medium,camera,film,sampler
+	},
+}
+
+% Thick frames for images
+\setlength\fboxsep{0pt}
+\setlength\fboxrule{1.5pt}
+
+\lstnewenvironment{cpp}[1][]{\lstset{language=c++, #1}}
 	{}
-\lstnewenvironment{xml}{\lstset{language=xml}}
+\lstnewenvironment{xml}[1][]{\lstset{language=xml, #1}}
 	{}
-\lstnewenvironment{shell}{\lstset{language=bash}}
+\lstnewenvironment{shell}[1]{\lstset{language=bash, #1}}
 	{}
 \lstnewenvironment{console}[1][]{\lstset{basicstyle=\footnotesize\ttfamily, float, #1}}
 	{}
@@ -98,7 +122,8 @@
 % ----- 8< ----- 8< ------
 
 \title{
-	Mitsuba Documentation
+	Mitsuba Documentation\\\vspace{3mm}
+	\large Version \MitsubaVersion
 }
 \author{Wenzel Jakob}
 \date{\today}

doc/section_bsdf.tex

@@ -0,0 +1,47 @@
+\subsection{Surface scattering models}
+Surface scattering models describe the way in which light reflects
+from surfaces in the scene. Even slight adjustments to such a description
+can significantly change the appearance of a rendering.
+To achieve realistic results, Mitsuba comes with a library of 
+both general-purpose models (smooth or rough glass, metal, plastic, ..) and 
+more specialized models (woven cloth, masks, ..).
+
+Throughout the documentation and within the scene description language, 
+the word \emph{BSDF} is used synonymously with the term ``surface
+scattering model''. This is an abbreviation for 
+\emph{Bidirectional Scattering Distribution Function}, a more 
+precise technical description of the model's properties.
+
+In Mitsuba, BSDFs are assigned to \emph{shapes}, which
+describe the visible surfaces in the scene. In the scene 
+description language, this assignment must
+either be performed by nesting BSDFs within shapes, 
+or they can be named and then later referenced 
+by by name.
+
+The following fragment shows an example of both kinds of usages:
+\begin{xml}
+<scene>
+	<!-- Creating a named BSDF for later use -->
+	<bsdf type=".. BSDF type .." id="myNamedMaterial">
+		<!-- BSDF parameters go here -->
+	</bsdf>
+
+	<shape type="sphere">
+		<!-- Example of referencing a named material -->
+
+		<ref id="myNamedMaterial"/>
+	</shape>
+
+	<shape type="sphere">
+		<!-- Example of using an unnamed material -->
+
+		<bsdf type=".. BSDF type ..">
+			<!-- BSDF parameters go here -->
+		</bsdf>
+	</shape>
+</scene>
+\end{xml}
+It is generally more economical to use named BSDFs when they
+are used in several places, since this reduces Mitsuba's internal
+memory usage.

src/bsdfs/lambertian.cpp

@@ -24,6 +24,15 @@
 MTS_NAMESPACE_BEGIN
 
 /*! \plugin{lambertian}{Ideally diffuse / Lambertian material}
+ *
+ * \begin{center}
+ * \begin{tabular}{c@{\hspace{1cm}}c}
+ * \fbox{\includegraphics[width=6cm]{images/bsdf_lambertian_plain.jpg}}&
+ * \fbox{\includegraphics[width=6cm]{images/bsdf_lambertian_textured.jpg}}\\
+ * Homogeneous reflectance, see \lstref{lambertian-uniform}&
+ * Textured reflectance, see \lstref{lambertian-textured}
+ * \end{tabular}
+ * \end{center}
  *
  * The Lambertian material represents an ideally diffuse material
  * with the specified amount of reflectance. When nothing is specified,
@@ -35,9 +44,17 @@ MTS_NAMESPACE_BEGIN
  * back side, it will be completely black. If this is undesirable, 
  * consider using the \pluginref{twosided} BRDF adapter plugin.
  *
- * \begin{xml}
+ * \begin{xml}[caption=Reflectance specified as an sRGB color, label=lst:lambertian-uniform]
  * <bsdf type="lambertian">
- *   <srgb name="reflectance" value="#a4da85"/>
+ *   <srgb name="reflectance" value="#6d7185"/>
+ * </bsdf>
+ * \end{xml}
+ *
+ * \begin{xml}[caption=Lambertian material with a texture map, label=lst:lambertian-textured]
+ * <bsdf type="lambertian">
+ *   <texture type="ldrtexture" name="reflectance">
+ *     <string name="filename" value="wood.jpg"/>
+ *   </texture>
  * </bsdf>
  * \end{xml}
  */