Scene Tree Definition and Specification

• case,
• leading whitespace, and
• trailing whitespace,

• it is empty, or
• it starts with #.

The following subsections cover in detail the format of each node's specification in a scene file, as well as its response and precise effect on the traversal state, when encountered. The traversal state consists of

• the current material - iff the user has specified that the scene primitives be rendered as lit solids -,
• the current color, and
• the current modeling transformation.

Interior node

Group Begin

Group End

Also, right before the first child appears, i.e. immediately after the Group Begin delimiter, the node's name (or lack thereof) is specified on a separate line. This line must start with the Name keyword, followed by a mandatory colon and a single space, and end with an arbitrary string which becomes the node's name. The keyword <None> may be used in place of a name, in which case the node remains nameless.

When a Group node is encountered during traversal, it first saves the current traversal state, then it traverses its children, and concludes by restoring the traversal state to its saved configuration.

Leaf nodes

• Primitive
• Material
• Light
• Camera
• Static Transformation
• Joint Transformation

MOAN's primitives, rendered as lit solids.

A Primitive node requires a single additional line (besides the node type), which specifies the shape of the primitive. All the valid shape names are listed in the table below, in the first column.

When traversed, a Primitive node renders itself, using the current traversal state to determine the rendering parameters and the modeling transformation. The second column of the table describes the rendered object in detail, assuming an identity modeling transformation.

All objects except lines and discs are rendered by invoking some routine in the general purpose library for graphics applications, possibly after some elementary transformations are pushed on the modeling stack to provide consistent orientation between primitives. By contrast, lines and discs are always rendered using direct OpenGL calls, for efficiency. The user may specify whether all primitives but lines are rendered as lit solids or wireframes.

The third column in the table states where a shape appears in the above figure.

Shape name	Rendered object	Location in figure
Sphere	A unit sphere centered at the origin.	Center.
Cube	An axis-aligned cube with unit side length, and centered at the origin.	Middle row, right column.
Cylinder	An un-capped cylinder of unit radius, wrapped around the y axis and extending from y=-0.5 to y=0.5.	Top row, right column.
Line	A line segment lying on the y axis, and extending from y=-0.5 to y=0.5.	Top row, third column.
Icosahedron	An icosahedron whose vertices lie on a unit sphere centered at the origin.	Top row, second column.
Octahedron	An octahedron whose vertices lie on a unit sphere centered at the origin.	Top row, left column.
Tetrahedron	A tetrahedron whose vertices lie on a unit sphere centered at the origin.	Middle row, left column.
Dodecahedron	A dodecahedron whose vertices lie on a unit sphere centered at the origin.	Bottom row, left column.
Cone	An un-capped cone whose base has unit radius, whose axis is aligned with the y axis, and extending from y=-0.5 to y=0.5.	Bottom row, middle column.
Disc	A flat disc of unit radius lying on the xz plane.	Bottom row, right column. Shown rotated about the x axis by 90 degrees, for clarity's sake.

The scene file which was used to generate the above figure is primitives.sc.

A Material node requires five additional lines (besides the node type), each specifying one light reflection property of the material. All the valid property names are listed in the table below, in the first column.

Each property name is followed by a mandatory colon, a sequence of tabs and/or spaces, and some space- and/or tab-separated real numbers. Each of these numbers is called an argument, and all the arguments together comprise the value of the property; the number of arguments for each property is listed in the second column of the table.

The effect of a Material node on the traversal state is twofold:

1. it sets the values of the current material properties to the values of its own properties - iff the user has specified that the scene primitives be rendered as lit solids -, and
2. it sets the value of the current color to the value of its diffuse property.

The interpretation of properties and their values adheres to OpenGL's lighting model; for more information, consult chapter 6 of the The OpenGL Programming Guide and/or the on-line manual pages for glMaterial*().

Property name	Number of arguments
Ambient	4
Diffuse	4
Specular	4
Emission	4
Shininess	1

A Light node requires five additional lines (besides the node type), each specifying one property of the light source. All the valid property names are listed in the table below, in the first column.

Each property name is followed by a mandatory colon, a sequence of tabs and/or spaces, and then some space- and/or tab-separated arguments; the number and type of arguments for each property are listed in the second and third columns of the table.

When a Light node is encountered during traversal,

1. it enables the OpenGL light whose ID is the one given by the value of the node's ID property, and
2. configures the light emission properties and the light position of that OpenGL light to reflect the values of the node's remaining properties.

The interpretation of the light emission properties and the light position adheres to OpenGL's lighting model; for more information, consult chapter 6 of the The OpenGL Programming Guide and/or the on-line manual pages for glLight*().

Property name	Number of arguments	Argument type
ID	1	Integer between 0 to 7 (both ends included)
Ambient	4	All reals
Diffuse	4	All reals
Specular	4	All reals
Position	4	All reals

Caution: By default, no OpenGL lights are enabled, and thus all scene objects except lines are invisible. At least one light needs to be specified to make objects visible. For example, to simulate the effect of the sun shining from directly behind the camera, the following light specification can be used:

Light
 ID: 0
 Ambient: 1 1 1 1
 Diffuse: 1 1 1 1
 Specular: 1 1 1 1
 Position: 0 0 1 0

A Camera node requires three additional lines (besides the node type), specifying the camera properties and their values.

The first property of a camera is its name. It is specified in a line by itself, using the Name keyword, followed by a mandatory colon and a single space, and then its argument, which is an arbitrary string. Unlike other nodes with a name property, a Camera node must always be named; that is, the argument <None> does not make the camera nameless.

The second property of a camera is its type. Its specification commences with a line starting with the Type keyword, followed by a mandatory colon and a single space. The first argument of the property follows. This can be either

• Perspective, for a perspective projection camera, or
• Orthographic, for an orthographic projection camera.

On the next line, all the remaining arguments, some space- and/or tab-separated real numbers, appear. The number of the remaining arguments depends on the first argument:

Perspective projection camera

It has three additional arguments, comprising, in order,

1. the distance from the camera to the near clipping place,
2. the distance from the camera to the far clipping place, and
3. the camera's vertical field of view, in degrees.

Both distance must be positive, with the near distance strictly smaller than the far distance. Also, the field of view must be positive and strictly smaller than 180.

Orthographic projection camera

It has two additional arguments, namely the distances to the near and far clipping planes. These arguments are constrained in the same way as the corresponding arguments of a perspective projection camera.

When a Camera node is encountered during traversal,

1. the adjoint A of the current modeling transformation matrix is calculated,
2. A post-multiplies a regular viewing matrix whose entries are determined by the node's type property and its value - this matrix is generated using glOrtho() or gluPerspective(), depending on the first argument -, and
3. the result becomes the new viewing transformation.
The overall effect is that the camera is placed at the same point in space as a primitive would have been placed if the Camera node were to be turned into a Primitive node; that is, the camera looks at the scene from that (hypothetical) primitive's point of view. In algebraic terms, the current modeling transformation matrix is treated as the matrix defining the transformation from the camera coordinate system to the global coordinate system.

A Static Transformation node requires two additional lines (besides the node type), specifying the static transformation property and its value.

The only property of a static transformation is its type. Its specification commences with a line starting with the Type keyword, followed by a mandatory colon and a single space. The first argument of the property follows. Valid values for this first argument appear in the first column of the table below.

On the next line, all the remaining arguments, some space- and/or tab-separated real numbers, appear. The number and interpretation of the remaining arguments depend on the first one; these are tabulated below, in the second and third columns respectively.

First argument	Number of remaining arguments	Interpretation
Translation	3	X, Y, and Z displacements.
Scale	3	X, Y, and Z scale factors.
Rotation	4	Angle of rotation, in degrees, followed by the X, Y, and Z components of the rotation axis.

When a Static Transformation node is encountered during traversal, it post-multiplies the current modeling matrix by a matrix effecting the transformation encoded in the node. To this end, the OpenGL calls glTranslate*(), glScale*(), or glRotate*() are used, depending on the first argument; for more information on these transformations and their parameters, see the pertinent manual pages.

A Joint Transformation node requires at least six additional lines (besides the node type), specifying the transformation properties and their values.

The first property of a joint transformation is its name (or lack thereof). It is specified in a line by itself, using the Name keyword, followed by a mandatory colon and a single space, and then its argument, namely an arbitrary string which becomes the node's name. The keyword <None> may be used in place of a name, in which case the node remains nameless.

The second property of a joint transformation is its type. Its specification commences with a line starting with the Type keyword, followed by a mandatory colon and a single space. The first argument of the property follows. Valid values for this first argument appear in the first column of the table above.

The remaining arguments of the type property appear between the delimiters

Keyframes Begin

and

Keyframes End

each delimiter occupying a line of its own. Between these delimiters, two or more lines appear, each containing some space- and/or tab-separated real numbers.
• The first argument on each line is the keyframe number, a number between 0 and 1 (both ends included): 0 corresponds to the first keyframe, and 1 corresponds to the last keyframe. When the scene is loaded in MOAN, these keyframe numbers are translated into integers, the integer range determined by the user.

• The rest of these arguments specify the parameters of the transformation encoded in the node at the associated keyframe. Their number and interpretation appear in the table above, in the second and third columns respectively.

The two required lines should correspond to the first and last keyframe.

When a Joint Transformation node is encountered during traversal, it behaves in almost the same way as a Static Transformation node. The only difference is that Joint Transformation nodes take into account the user-specified

• animation frame, and
• keyframe interpolation method,
when modifying the current modeling transformation. Thus, each of the parameters of a Joint Transformation node (e.g. the X, Y, and Z displacements for a translation) are
• first interpolated separately; that is, their values at the user-specified animation frame are determined by interpolating their values at keyframes. And then,
• the interpolated values are used to form the matrix which post-multiplies the current modeling matrix.

Caution: Interpolating the axis of rotation can produce unintuitive, albeit semantically correct, results.