YafaRay XML scene specifications

XML Document Structure

Each XML document should start with naming the XML version: <?xml version="1.0"?>
The only top-level element supported by YafaRay is exactly one scene element.

Example:
<scene>
...scene elements...
</scene>

There now are two scene modes, a triangle-only mode (type="triangle", the default) and a "universal" mode that allows for other primitives too (which sacrifices some memory and performance though, can't have everything...)
A universal scene would start with:
<scene type="universal">

Parameters

Most scene elements take a set of parameters, that are passed as sorted parameter map to the "factories" internally. A parameter consists of name and value, while the type of the value is important. In the XML file, the parameter name is the element name, and the value is expressed by one or several attributes as following.

Attribute types

Each parameter must have exactly one of the folling XML attribute sets:

  • ival: an integer value (everything that fits withing a signed 32bit integer currently).
    Example: ival="12"
  • fval: a floating point value, converted to 64bit double precision float values.
    Examples: fval="1", fval="3.5e-2", fval=".75"
  • bval: a boolean value, value can either be "true" and "false".
    Example: bval="false"
  • sval: a string value. Certain restriction apply however. It must not contain double quotes, also white space and newline characters should not be used.
    Example: sval="/home/images/wood.tga"
  • r, g, b, a: a quadruple of float attributes (values as in fval) describing a color.
    Example: r="0" g="0.4" b="1" a="1"
  • x, y, z: a triple of float attributes describing a point.
    Example: x="0" y="1e5" z="10.5"

So a complete parameter looks like below:
Example: <samples ival="16"/>
This specifies the parameter "samples" to be an integer with the value 16.

Example: <center x="0" y="1e-3" z="10.5">
This specifies a point with the coordinates (0.0, 0.001, 10.5)

Scene Elements

The possible scene elements are currently:

  • texture
  • material
  • mesh
  • smooth
  • light
  • background
  • camera
  • integrator
  • render

All those elements except "mesh" and "render" need to have an attribute "name" and are described by a set of parameters. Mesh and render are described in separate sections, because they are not related to plugins and hence have different rules.
Example:
<texture name="Tex1">
<type sval="marble"/>
...more attributes...
</texture>

All elements nested inside are interpreted as parameters and hence have to conform to the syntax described above. One required string parameter typically is "type", except for the render an mesh element. The possible types obviously depends on the installed plugins, and the parameters recognized obviously depend on the plugin.

Materials can have an additional list of parameter sets, e.g. to describe shader nodes. A parameter list entry is specified by a "list_element" tag.
Example:
<material name="Floor">
...attributes...
<list_element>
...attributes...
</list_element>
</material>

Mesh

The mesh can have several attributes:

  • vertices: integer; the number of vertices in the mesh; not mandatory, but helps memory managment a lot!
  • faces: integer; the number of faces (=triangles) in the mesh; again, not mandatory, but recommended.
  • has_orco: boolean; indicate that vertices also store and additional "original" coordinate. "false" if omitted.
  • has_uv: boolean; indicate that faces also store information to uv-coordinates. "false" if omitted.
  • type: integer; the type of mesh; 0 if omitted. Types larger than 0 only apply to universal scene mode.

Example:
<mesh vertices="8" faces="6" has_orco="true" has_uv="true" type="0">
</mesh>

The possible elements of a mesh are "p" (point), "uv" (UV-coordinate) "f" (face) and "set_material".

A point takes the attributes x, y and z, and if has_orco is true additionally ox, oy and oz for the original coordinates.
Example: <p x="1.5" y="1" z="0"/> (has_orco="false")
Example: <p x="1.5" y="1" z="0" ox="0.5" oy="1" oz="-1"/> (has_orco="true")

A UV-coordinate obviously requires the attributes u and v.
Example: <uv u="0" v="1"/>

A face (triangle) element takes the indices of point coordinates and if has_uv is 'true', the UV-indices.
Example: <f a="0" b="1" c="2"/> (has_uv="false");
Example: <f a="0" b="1" c="2" uv_a="3" uv_b="4" uv_c="5"/> (has_uv="true");

The set_material directive sets the material to be used for following faces. So this must occur before any face, and can be used arbitrarily often to set a new material, but for minimum overhead the faces should be sorted by material so you need this element only once for each different material occuring.
Example: <set_material sval="MAMaterial"/>

NOTE: Mesh elements should be defined before they are referenced. Although it currently is not mandatory, this could change in the future. This means, if you create a face, the points (and if used, uv-coordinates) it is made of should already have been defined! For example, first define all points, then all UVs and then all faces. The way blender works currently exports all points first, and then UVs, face, UVs, face etc

Smooth

This block requests creation of smoothed normals for a mesh (must already exist). In XML files, meshes get IDs from 1 upwards in the order they were defined. This block takes two attributes:

  • ID: the mesh ID to be smoothed
  • angle: the smoothing threshold angle in degrees

Example: <smooth ID="3" angle="50"/>

Render

The render element itself has no attributes and again just lists parameters. These parameters are all related to the actual rendering of the scene, like resolution, antialiasing settings, camera and integrator(s) to use and settings of the "image film".
Example:
<render>
<AA_minsamples ival="4"/>
<AA_passes ival="0"/>
<AA_pixelwidth fval="1.5"/>
<AA_threshold fval="0.05"/>
<background_name sval="world_background"/>
<camera_name sval="CACamera"/>
<integrator_name sval="default"/>
<clamp_rgb bval="true"/>
<exposure fval="0"/>
<gamma fval="1"/>
<width ival="800"/>
<height ival="600"/>
<threads ival="1"/>
</render>

-- MathiasWein - 19 Nov 2006