====== FART Scene File Syntax ======

This document describes the syntax of the scene description files used by the [[..:fart|FART Raytracer]].

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

===== Example Scene Description File =====

First, a simple example:


{{ :projects:fart:syntax:simple.png?nolink}}
<code>
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>
        }
    }
}
</code>

===== Scene Loading Phases =====

Scene description files are loaded in three phases.

==== Phase 1 : Initial Parsing ====

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.

==== Phase 2 : Script Execution ====

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.

==== Phase 3 : Scene Construction ====

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.

===== Scene Description File Elements =====

==== Identifiers ====

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:
<code>IDENTIFIER ::= [a-zA-Z_][a-zA-Z_0-9]*</code>

==== Object Elements ====

=== scene ===

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

Syntax:
<code>
scene {
  scene_items
}
</code>

//scene_items// can be any of:
  * [[#options]]
  * [[#light]]
  * [[#camera]]
  * Any scripting element
  * Any transform block
  * Any shape element

=== options ===

Syntax:
<code>
options {
  options_items
}
</code>

//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 [[..:fart#executing|Executing FART]].

=== camera ===

Syntax:
<code>
camera {
  camera_items
}
</code>

//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).

=== light ===

Syntax:
<code>
light {
  light_items
}
</code>

//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.

==== Scripting Elements ====

=== Variables ===

Syntax: <code>VARIABLE ::= $[a-zA-Z_][a-zA-Z_0-9]*</code>

Variables, which are only used during the [[#Scene Loading Phases|execution phase]], are differentiated from identifiers by a preceding "''$''" symbol.

Variables can be declared by simply assigning to them: <code>$x = 42</code>

If a variable ''$x'' exists in an outer scope but a newly scoped ''$x'' is desired, one can be created with the ''local'' keyword:
<code>local $x</code>
or
<code>local $x = 42</code>

=== Expressions ===

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 loop ===

<code>
for (initial_expression; test_expression; post_expression)
{
  for_items
}
</code>

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

=== while loop ===

<code>
while (test_expression)
{
  while_items
}
</code>

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

=== if ===

<code>
if (expression)
{
  elements
}
elsif (expression)
{
  elements
}
else
{
  elements
}
</code>

Works like in C.

=== Built-in Functions ===

Function calls look like they do in C. Here's how to call built-in functions:
<code>
function_call ::= IDENTIFIER '(' parameters ')'

parameters ::=
parameters ::= expression more_parameters

more_parameters ::=
more_parameters ::= COMMA expression more_parameters
</code>

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''