format documentation is done

doc/format.tex

@@ -1,12 +1,13 @@
 \section{Scene file format}
 Mitsuba uses a very simple and general XML-based format to represent scenes.  
-The framework's underlying approach is to represents discrete blocks of functionality as plugins, 
+Since the framework's philosophy is to represent discrete blocks of functionality as plugins, 
-hence a scene file can essentially be interpreted as description that determines which 
+a scene file can essentially be interpreted as description that determines which 
 plugins should be instantiated and how they should be interface with each other.
 In the following, we'll look at a few examples to get a feeling for the scope of the
 format.
 
-An simple scene might looks like this
+An simple scene with a single mesh and the default lighting and camera setup might look
+something like this:
 \begin{xml}
 <?xml version="1.0" encoding="utf-8"?>
 <scene>
@@ -17,14 +18,15 @@ An simple scene might looks like this
 \end{xml}
 This example already contains the most important things to know about format: you can have
 \emph{objects} (such as the objects instantiated by the \code{scene} or \code{shape} tags), which are allowed to be nested within
-each other. Each object optionally accepts \emph{properties} (such as \code{string}),
+each other. Each object optionally accepts \emph{properties} (such as the \code{string} tag),
 which further characterize its behavior. All objects except for the root object (the \code{scene})
 cause the renderer to load and instantiate a plugin, hence you must provide the plugin name using
 \code{type=".."} parameter. 
 
-The tags let the renderer know what kind of object is to be instantiated: for instance \code{obj} is a
+The object tags also let the renderer know \emph{what kind} of object is to be instantiated: for instance, 
-WaveFront OBJ loader, which conforms to the \emph{Shape} interface. Similarly,
+any plugin loaded using the \code{shape} tag must conform to the \emph{Shape} interface, which
-you could write
+the certainly case for the plugin named \code{obj} (it contains a WaveFront OBJ loader).
+Similarly, you could write
 \begin{xml}
 <?xml version="1.0" encoding="utf-8"?>
 <scene>
@@ -45,8 +47,6 @@ and one or more luminaires. Here is a more complex example:
 	<integrator type="path"> <!-- Path trace an 8-bounce GI solution -->
 		<integer name="maxDepth" value="8"/>
 	</integrator>
-
-	
 	<!-- Instantiate a perspective camera with 45 degrees field of view -->
 	<camera type="perspective">
 		<!-- Rotate the camera around the Y axis by 180 degrees -->
@@ -92,14 +92,15 @@ and one or more luminaires. Here is a more complex example:
 	</shape>
 </scene>
 \end{xml}
-This example introduces several new object types (\code{integrator, camera, sampler, film, bsdf}, and \code{luminaire})
+\newpage
-and a few property types (\code{integer}, \code{transform}, and \code{rgb}). 
+This example introduces several new object types (\code{integrator, camera, bsdf, sampler, film}, and \code{luminaire})
-Objects are usually declared at the top level except if there is some
+and property types (\code{integer}, \code{transform}, and \code{rgb}). 
-inherent relation that links them to another object. For example, BSDFs are usually specific to a certain geometric object, so 
+As you can see in the example, objects are usually declared at the top level except if there is some
-they appear as a child object of a shape. Similarly, the sampler and film both affect the way in which
+inherent relation that links them to another object. For instance, BSDFs are usually specific to a certain geometric object, so 
-rays are generated from the camera, hence they are nested inside it.
+they appear as a child object of a shape. Similarly, the sampler and film affect the way in which
+rays are generated from the camera and how it records the resulting radiance samples, hence they are nested inside it.
 
-Note that you should always put properties before nested child objects, otherwise you'll see something like the following slightly cryptic
+Note that you should always put properties \emph{before} nested child objects, otherwise you'll see something like the following slightly cryptic
  XML validation error. For instance,
 \begin{xml}
 ...
@@ -109,15 +110,135 @@ Note that you should always put properties before nested child objects, otherwis
 	</shape>
 ...
 \end{xml}
-produces 
+fails with this message:
 \begin{shell}
 Caught a critical exeption: 2010-08-11 03:23:31 ERROR main [src/mitsuba/shandler.cpp:359] Error in file "/home/wenzel/mitsuba/test.xml" (line 63): Element 'string' is not valid $\texttt{for}$ content model: '(((integer|float|point|vector|boolean|transform|string|spectrum|rgb)|blackbody),((bsdf|subsurface|ref)|luminaire))'
 \end{shell}
 \subsection{Property types}
+This section documents all of the ways in which properties can be supplied to objects. If you are more
+interested in knowing which properties a certain plugin accepts, you should look at the next section instead.
 \subsubsection{Numbers}
-\subsubsection{Spectra}
+Integer and floating point values can be passed as follows:
-\subsubsection{Transformations}
+\begin{xml}
-\subsubsection{Vectors, Positions}
+<integer name="intProperty" value="1234"/>
+<float name="floatProperty" value="1.234"/>
+<float name="floatProperty2" value="-1.5e3"/>
+\end{xml}
+Note that you must adhere to the format expected by the object, i.e. you can't pass an integer property
+to an object, which expects a floating-point value associated with that name.
 \subsubsection{Strings}
-\subsection{Instancing materials}
+Passing strings is very straightforward:
+\begin{xml}
+<string name="stringProperty" value="This is a string"/>
+\end{xml}
+\subsubsection{Color spectra}
+There are several different ways of passing color spectra to objects, which can be used interchangeably.
+The most basic one is to supply linear RGB values as floating-point triplets or hex values
+\begin{xml}
+<rgb name="spectrumProperty" value="0.2, 0.8, 0.4"/>
+<rgb name="spectrumProperty" value="#f9aa34"/>
+\end{xml}
+When Mitsuba is compiled with the default settings, it internally uses linear RGB to represent colors, so
+these values are directly used. The renderer can also be configured to sample the color spectrum using a specified
+number of samples, in which case the RGB values are first converted into spectra using a simple heuristic.
+
+You can also directly supply the spectral color samples that Mitsuba internally uses if spectral rendering is
+active. This unfortunately closely couples the interpretation of a scene to how Mitsuba is compiled, which can be a disadvantage.
+For instance, the below example assumes that 6 spectral samples are being used:
+\begin{xml}
+<spectrum name="spectrumProperty" value="0.2, 0.8, 0.4, 0.6, 0.1, 0.9"/>
+\end{xml}
+A safer way is to specify a linearly interpolated spectral power distribution, which is converted into
+the internal spectral representation as the scene is loaded.
+\begin{xml}
+<spectrum name="spectrumProperty" value="400:0.56, 500:0.18, 600:0.58, 700:0.24"/>
+\end{xml}
+This is essentially a mapping from wavelength in nanometers (before the colon) to a reflectance or intensity value (after the colon). Missing values are linearly interpolated from the two closest neighbors.
+
+Finally, it is also possible to specify the spectral distribution of a black body emitter, where the temperature is given in Kelvin.
+\begin{xml}
+<blackbody name="spectrumProperty" temperature="10000"/>
+\end{xml}
+\subsubsection{Vectors, Positions}
+Points and vectors can be specified as follows:
+\begin{xml}
+<point name="pointProperty" x="3" y="4" z="5"/>
+<vector name="vectorProperty" x="3" y="4" z="5"/>
+\end{xml}
+It is important that whatever you choose as world-space units (meters, inches, etc.) is 
+used consistently in all places.
+\subsubsection{Transformations}
+Transformations are the only kind of property, which require more than a single tag. The idea is that, starting
+with the identity, you build up a transformation using nested commands. For instance, a transformation that 
+does a translation followed by a rotation might be written like this:
+\begin{xml}
+<transform name="trafoProperty">
+	<translate x="-1" y="3" z="4"/>
+	<rotate y="1" angle="45"/>
+</transform>
+\end{xml}
+Mathematically, each incremental transformation in the sequence is left-multiplied onto the current one. The following
+choices are available:
+\begin{itemize}
+\item Translations, e.g.
+\begin{xml}
+<translate x="-1" y="3" z="4"/>
+\end{xml}
+\item Rotations around a specified direction. The angle is given in degrees, e.g.
+\begin{xml}
+<rotate x="0.701" y="0.701" z="0" angle="180"/>
+\end{xml}
+\item Scaling operations. The coefficients may also be negative to obtain a flip, e.g.
+\begin{xml}
+<scale x="2" y="1" z="-1"/>
+\end{xml}
+\item Explicit 4$\times$4 matrices, e.g
+\begin{xml}
+<matrix value="0 -0.53 0 -1.79 0.92 0 0 8.03 0 0 0.53 0 0 0 0 1"/>
+\end{xml}
+\item LookAt transformations --- this is useful for setting up the camera. The \textbf{o} coordinates
+provide the camera origin, \textbf{t} specifies the target and \textbf{u} is the ``up'' direction.
+\begin{xml}
+<lookAt ox="10" oy="50" oz="-800" tx="0" ty="0" tz="0" ux="0" uy="1" uz="0"/>
+\end{xml}
+\end{itemize}
+Cordinates that are zero (for \code{translate} and \code{rotate}) or one (for \code{scale})
+do not explicitly have to be specified.
+\newpage
+\subsection{Instancing}
+Quite often, you will find yourself using an object (such as a material) in many places. To avoid having
+to declare it over and over again, which wastes memory, you can make use of references. Here is an example
+of how this works:
+\begin{xml}
+<scene>
+	<texture type="ldrtexture" id="myImage">
+		<string name="filename" value="textures/myImage.jpg"/>
+	</texture>
+
+	<bsdf type="lambertian" id="myMaterial">
+		<!-- Reference the texture named myImage and pass it 
+			to the BRDF as the reflectance channel -->
+		<ref name="reflectance" id="myImage"/>
+	</bsdf>
+
+	<shape type="obj">
+		<string name="filename" value="meshes/myShape.obj"/>
+
+		<!-- Reference the material named myMaterial -->
+		<ref id="myMaterial"/>
+	</shape>
+</scene>
+\end{xml}
+Note that this feature cannot yet be used to do geometry instancing.
 \subsection{Including external files}
+A scene can be split into multiple pieces for better readability. 
+to include an external file, please use the following command:
+\begin{xml}
+<include filename="nested-scene.xml"/>
+\end{xml}
+In this case, the file \code{nested-scene.xml} must still be a proper scene file with a \code{<scene>} tag at the root.
+This feature is sometimes very convenient in conjunction with the \code{-D key=value} flag of the \code{mitsuba} command line renderer (see the previous section for details).
+This lets you include different parts of a scene configuration by changing the command line parameters (and without having to touch the XML file):
+\begin{xml}
+<include filename="nested-scene-$\texttt{\$}$version.xml"/>
+\end{xml}

doc/main.tex

@@ -79,7 +79,8 @@
 	keywordstyle = \bfseries,
 	commentstyle=\color{lstcomment}\itshape,
 	basicstyle = \small\ttfamily,
-	breaklines = true
+	breaklines = true,
+	showstringspaces = false
 }
 
 \lstnewenvironment{cpp}{\lstset{language=c++}}