Format of the Descriptive Scene File Language


The parser accepts C++ style comments in both // and /* ... */ flavours. The
parser can recurse into other scene files with the

  #include "filename"

directive. After the end of the included file, parsing will continue past the
#include directive. There is no hardcoded limit on the nesting depth of include
files; the program will simply run out of memory in case of an endless
recursion.

All literal numbers are parsed as double precision floating point values.
Vector quantities are enclosed in angular brackets < and >, and the individual
coordinates are separated by whitespace.

A recurring pattern in scene files are tag lists. Those are enclosed in curly
brackets { and }, and contain one or more tag keywords, each with an optional
value. The value's type is implied by the specific tag (either float, vector,
or none, which means the presence or absence of a tag keyword conveys all
relevant information). The meaning of a tag list is specific to its owner, thus
tag keywords are somewhat context sensitive. However, within a tag list the
order of individual tags does not matter.


Boar's very simple illumination model is controlled by a "material" tag list:

material {
  pigment <red green blue>  // colour components in the range [0 .. 1]
  ambient fraction          // percentage of filler light in the range [0 .. 1]
  diffuse fraction          // percentage of direct light
  highlight intensity       // brightness of reflected light sources
  roughness value           // controls size of highlights
  reflection fraction       // percentage of reflected light
}


Geometric objects can be transformed after instantiation:

scale <x y z>       // one non-zero scale factor per axis
translate <x y z>   // just a vector specifying the movement
rotatex angle       // rotation around x axis, angle in degrees
rotatey angle
rotatez angle
rotate <anglex angley anglez>  // applied in the order X, Y, and Z
transform <column1> <column2> <column3>  // generic matrix

Such transformations can be concatenated simply by listing them in the scene
file one after another.


Boar is a solid modeler that supports Constructive Solid Geometry with
arbitrary quadric objects. Another object attribute besides transforms and a
"material" tag list is the "Invert" modifier. This keyword turns a quadric or
a CSG object inside out. If you want to invert an object, the keyword must be
specified as the very first object attribute, before any transforms or
material. Thus all geometric primitives match this pattern:

primitive_type { specific_parameters
  invert         // optional modifier
  invisible      // optional modifier, see below
  transform(s)   // optional (affects object)
  material {     // if unspecified, enclosing CSG object must have material
    ...
  }
  transform(s)   // optional (affects material along with object)
}

The "Invisible" modifier turns off ray intersections for one primitive object.
So invisible quadrics can be used to clip or trim other (visible!) quadric
surfaces with CSG. The "Invisible" keyword must be specified before any
transforms or materials, but after a possible "Invert" keyword. CSG composite
objects do not understand the "Invisible" keyword; the components of a CSG must
be flagged individually.


The parser currently understands the following quadric primitives:

sphere {<centerPoint> radius}

cylinder {<point1> <point2> radius}
// infinitely long cylinder, the axis of which passes through the two points

cone {<point1> radius1 <point2> radius2}
// infinitely long double-cone, with axis passing through given points

slab {<point1> <point2>}
/* the volume between two parallel planes passing through the two points;
   plane normal vectors are parallel to (point2 - point1) */

planes {<point1> <normal1> <point2> <normal2>}
// XOR of two planes (algebraic product of two plane equations)

quadric {<a b c> <d e f> <g h i> j}
/* arbitrary quadric with the given coefficients

                2    2    2
   q(x,y,z) = ax + by + cz + dyz + ezx + fxy + gx + hy + iz + j

   surface is displayed wherever q(x,y,z) = 0 */

lathepiece {<radius1 y1> <radius2 y2> displacement}
// (possibly infinite) quadric of revolution around Y axis


Additionally, the parser handles a few composite objects for convenience:

cappedcylinder {...}
cappedcone {...}
cappedlathepiece {...}

which behave exactly like their infinite counterparts, but their extent is
limited to the specified axis points and they are closed with planar surfaces.
Finally there is

box {<minvector> <maxvector>}
// axis aligned box

as the last convenience object.


Constructive Solid Geometry is handled with the usual base operators:

union/intersection/difference {
  invert          // optional modifier
  object {...}
  transform(s)    // optional, affects all objects above it
  object {...}
  transform(s)    // optional
  ...             // possibly more than two objects
  material {...}  // optional, affects all enclosed objects without material
  transform(s)    // optional
}

Additionally there is a special operator

stitch {
  separator_quadric  // a primitive quadric that provides an invisible border
  inner_object       // a generic object that is visible inside the separator
  transform(s)       // optional, affects inner and separator
  outer_object       // a generic object that is visible outside the separator
  transform(s)       // optional
  material {...}     // optional, affects components without material
  transform(s)       // optional 
}

This is a bit tricky to use correctly. The separator_quadric is invisible,
so the user must ensure a seamless fit of inner and outer object at the seam.


For lighting, Boar only supports an unlimited number of primitive point lights:

pointlight {<positionvector> <red green blue>}


And of course a simple pinhole camera:

camera {
  eye      <observer_position>
  lookat   <focus_of_interest>
  sky      <global_upwards_direction>
  width    view_rect_width
  height   view_rect_height
  distance view_rect_distance_from_eye
}

That's all there is to it.