FART Scene File Syntax

This document describes the syntax of the scene description files used by the FART Raytracer.

Scene description files are represented in an ASCII-based, hierarchical language.

First, a simple example:

scene {
    options {
        width 400
        height 300
    }
    camera {
        position <5, -5, 4>
        look_at <0, 0, 1>
    }
    light {
        position <10, -10, 50>
    }
    plane {
        position <0, 0, 1>, 0
        material {
            color <0, 1, 0.2>
            reflectance 0.4
        }
    }
    sphere {
        radius 1
        translate <0, 0, 1>
        material {
            color <1, 1, 0>
        }
    }
}

Scene description files are loaded in three phases.

First, the scene file is parsed and a tree of nodes is created. Basic syntax errors are caught at this point, but placement of nodes is not (such as a “plane” containing a “radius”, or such). for(), while(), if(), and other scripting nodes are simply stored as regular nodes in the tree.

After the parse tree has been made, it is traversed in order, and scripting nodes are executed. The result of this phase is a new node tree devoid of any scripting nodes, and with exactly one object node for every object in the scene.

The node tree produced in phase 2 is traversed (not necessarily in order) in order to build the scene objects which will be used while rendering the scene.

In various elements, identifiers are required, for example, when giving a name to reusable shapes or materials for easy reference later.

The format of an identifier is:

IDENTIFIER ::= [a-zA-Z_][a-zA-Z_0-9]*

Every scene file must have exactly one scene node, and it must be the top-level node in the file.

Syntax:

scene {
  scene_items
}

scene_items can be any of:

• options
• light
• camera
• Any scripting element
• Any transform block
• Any shape element

Syntax:

options {
  options_items
}

options_items can be any of:

• width n - set the rendered image width to n (default 800).
• height n - set the rendered image height to n (default 600).
• multisample n - set the multisample level to n (default 3). The number of samples per pixel is given by n^2.
• ambient_occlusion n - set the ambient occlusion level to n (default 0, inactive). Level can be 0 (inactive) through 9 (slow).
• max_depth n - set the maximum depth that ray recursion is allowed to hit (default 10).
• exposure f - set the exposure level to f (default 1.0).
• ambient v - set the global ambient light to v (default <0.2, 0.2, 0.2>).

Most of these options can be overridden from the command line. See Executing FART.

Syntax:

camera {
  camera_items
}

camera_items can be any of:

• position v - set eye point of camera to v (default <0, 0, 0>).
• look_at v - set focal point of camera to v (default <0, 1, 0>).
• up v - set “up” vector for camera to v (default <0, 0, 1>).
• vfov f - set the vertical field-of-view to f (default 60.0).

Syntax:

light {
  light_items
}

light_items can be any of:

• position v - set light position to v (default <0, 0, 0>).
• diffuse v - set light diffuse color to v (default <1, 1, 1>).
• specular v - set light specular color to v (default <1, 1, 1>).
• color v - set light diffuse and specular color to v (default <1, 1, 1>).
• radius f - set light radius to f (default 1.0). This is only used with jitter > 1.
• jitter n - set light jitter level to n (default 1). This is used to effect soft shadows. The higher the jitter level, the more points are used to approximate the soft shadow, and the longer the render takes.

Syntax:

VARIABLE ::= $[a-zA-Z_][a-zA-Z_0-9]*

Variables, which are only used during the execution phase, are differentiated from identifiers by a preceding “$” symbol.

Variables can be declared by simply assigning to them:

$x = 42

If a variable $x exists in an outer scope but a newly scoped $x is desired, one can be created with the local keyword:

local $x

or

local $x = 42

Operators:

• + (plus)
• - (minus)
• * (times)
• / (divide)
• % (modulus)
• = (assignment)
• == (equality comparison)
• != (not equals)
• ! (boolean NOT)
• && (boolean AND)
• || (boolean OR)

The operators were designed to work like they work in C. The arguments to modulus are converted to integers.

for (initial_expression; test_expression; post_expression)
{
  for_items
}

The for loop works like in C. Pretty much anything can go in for_items.

while (test_expression)
{
  while_items
}

Once again, pretty much any element can appear inside while_items.

if (expression)
{
  elements
}
elsif (expression)
{
  elements
}
else
{
  elements
}

Works like in C.

Function calls look like they do in C. Here's how to call built-in functions:

function_call ::= IDENTIFIER '(' parameters ')'

parameters ::=
parameters ::= expression more_parameters

more_parameters ::=
more_parameters ::= COMMA expression more_parameters

Here are the built-in functions supported:

• cos(x) - return cosine of x
• sin(x) - return sine of x
• abs(x) - return absolute value of x
• sqrt(x) - return the square root of x