\section{Scene file format}
Mitsuba uses a very simple and general XML-based format to represent scenes.
Since the framework's philosophy is to represent discrete blocks of functionality as plugins,
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 with a single mesh and the default lighting and camera setup might look
something like this:
\begin{xml}
\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 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 object tags also let the renderer know \emph{what kind} of object is to be instantiated: for instance,
any plugin loaded using the \code{shape} tag must conform to the \emph{Shape} interface, which
the certainly case for the plugin named \code{obj} (it contains a WaveFront OBJ loader).
Similarly, you could write
\begin{xml}
\end{xml}
This loads a different plugin (\code{sphere}) which is still a \emph{Shape}, but instead represents
a sphere configured with a radius of 10 world-space units. Mitsuba ships with
a large number of plugins; please refer to the next chapter for a reference.
The most common scene setup is to declare an integrator, some geometry, a camera, a film, a sampler
and one or more luminaires. Here is a more complex example:
\begin{xml}
\end{xml}
\newpage
This example introduces several new object types (\code{integrator, camera, bsdf, sampler, film}, and \code{luminaire})
and property types (\code{integer}, \code{transform}, and \code{rgb}).
As you can see in the example, objects are usually declared at the top level except if there is some
inherent relation that links them to another object. For instance, BSDFs are usually specific to a certain geometric object, so
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.
\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}
Integer and floating point values can be passed as follows:
\begin{xml}
\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}
Passing strings is very straightforward:
\begin{xml}
\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 or sRGB values as floating-point triplets or hex values
\begin{xml}
\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}
\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}
\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.
To specify a constant spectrum, simply provide just one value
\begin{xml}
\end{xml}
Finally, it is also possible to specify the spectral distribution of a black body emitter, where the temperature is given in Kelvin.
\begin{xml}
\end{xml}
\subsubsection{Vectors, Positions}
Points and vectors can be specified as follows:
\begin{xml}
\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}
\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}
\end{xml}
\item Rotations around a specified direction. The angle is given in degrees, e.g.
\begin{xml}
\end{xml}
\item Scaling operations. The coefficients may also be negative to obtain a flip, e.g.
\begin{xml}
\end{xml}
\item Explicit 4$\times$4 matrices, e.g
\begin{xml}
\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}
\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}