SGI YAODL: Summary from the Encyclopedia of Graphics File Formats

SGI YAODL File Format Summary

Also Known As: Yet Another Object Description Language, PowerFlip Format


Type 3D scene description
Colors Millions
Compression Uncompressed
Maximum Image Size Unlimited
Multiple Images Per File Yes
Numerical Format ASCII, big-endian
Originator Silicon Graphics
Platform SGI
Supporting Applications Powerflip
See Also SGI Inventor

Usage
A simple format used for storing 3D vector data.

Comments
YAODL is not widely used at Silicon Graphics and is constantly in danger of being rendered obsolete by more robust 3D imaging formats, such as SGI Inventor.

Sample images are available for this format.


YAODL (Yet Another Object Description Language) is a description language used for storing 3D object data to disk files. YAODL is a rather obscure format that was created specifically for the Silicon Graphics Powerflip demo program, and it is not widely supported by SGI. However, it is a simple example of a basic vector-object description language.

Contents:
File Organization
File Details
For Further Information

YAODL supports a small collection of object types, including NURBS, polygons, and quad-meshes. Object properties such as normals (facet or vertex), colors (object, facet, and vertex), and texture coordinates are also supported.

Advanced features of YAODL include hierarchical models, coordinate transformations (rotations, scales, translations, and so forth), and instancing (using the same data more than once).

File Organization

A YAODL file begins with the comment header #YAODL, followed by one or more YAODL objects. Each object can be completely independent of all other objects in the YAODL file, or it can rely on previously defined object data within the same file.

Each object may be written to a YAODL file using either an ASCII or binary data format. Therefore, a YAODL file may contain entirely ASCII data, entirely binary data, or a mixture of the two.

The advantage of ASCII objects is that they are easy to modify using a simple text editor and are portable between different machine platforms. And while binary objects are less portable, they are smaller and faster to load than their ASCII equivalents.

Comments may be inserted into ASCII YAODL files either by enclosing the comment in the Standard C comment tokens /* and */, or by including the UNIX shell-style comment # at the beginning of each line. All comments and white space characters are ignored by YAODL file parsers.

File Details

An ASCII YAODL file contains one or more YAODL objects, delimited by commas. Each object may have one of the following syntaxes:

(object_type  argument1, argument2, ... )
(object_type  argument1, ... :  property1, property2, ... )
integer integer integer ...
float float float ...
"some character String"
name = { one of the forms above }
name

Each YAODL object may contain zero or more arguments and have zero or more properties. For example, a colors object contains a minimum of three arguments:

(colors 0.0 1.0 0.0),

The three arguments here are RGB float values and define the color green. It is possible for many objects to have multiple groups of arguments. For example, a colors object may define more than one color, with each color represented by a set of three float values:

(colors 0.0 1.0 0.0  0.0 1.1 0.0  0.0 1.2 0.2),

An object may be used by other objects that take objects as their arguments or properties. For example, we may define a red polygon with four vertices in the following way:

(polygons
 (vertices -1. -1. 0.  1. -1. 0.  1. 1. 0.  -1. 1. 0.),
 : colors  0.0 1.0 0.0
),

Here we have a polygons object that takes one vertex's object as its argument and a color object as its properties. We can shorten this declaration by assigning a name to the colors object and using the new name in the properties list of the polygons object:

green = (colors	0.0 1.0 0.0),
(polygons
 (vertices -1. -1. 0.  1. -1. 0.  1. 1. 0.  -1. 1. 0.),  : green),

Note that the colors object, green, is a property of the polygons object, and object properties affect only the object to which they are assigned. The properties of each object must be explicitly specified or their default value(s) are assumed.

You probably have noticed that all the objects we've seen so far are described using their plural inflection, such as polygons rather than polygon. This is because it is possible to describe more than one rendered object within a YAODL object. For example, we could create three polygons, each red, green, and blue, using three polygon objects:

/* Three polygons */
red = (colors 1.0 0.0 0.0),
green = (colors	0.0 1.0 0.0),
blue = (colors 0.0 0.0 1.0),
(polygons
  (vertices -1. -1. 0.  1. -1.0.   1. 1. 0.  -1.  1. 0.),  : red),
(polygons
  (vertices  1. -1. 0.  1.  1.0.  -1. 1. 0.  -1. -1. 0.),  : green),
(polygons
  (vertices  1.  1. 0. -1.  1.0.  -1.-1. 0.   1. -1. 0.),  : blue),

Or we could nest all of these descriptions together to achieve exactly the same rendering using a single polygon object:

(polygons
 (vertices -1. -1. 0.   1. -1. 0.   1. 1. 0.   -1.  1. 0.),
 (vertices  1. -1. 0.   1.  1. 0.  -1. 1. 0.   -1. -1. 0.),
 (vertices  1.  1. 0.  -1.  1. 0.  -1. -1. 0.   1. -1. 0.),
 : colors 1.0 0.0 0.0  0.0 1.0 0.0  0.0 0.0 1.0,
),

It is important to realize that a YAODL reader does not perform any data type conversion, so be careful not to use an integer when a float is needed, and so on.

Normally, each name and object defined in an ASCII YAODL file has a global scope across the entire file starting at the point where it is defined. Braces { } may be used to create limited, block-scope variables within a YAODL file. Names defined within this local scope have precedence over identical names declared in the global scope and do not exist outside of their block.

blue = (colors 0.0 0.0 1.0), /* Define the color blue */
(polygons
  (vertices  1. 1. 0.   2. 2. 0.), : blue), /* Draw a blue line */
{
blue = (colors 0.0 0.15 1.0),
		  /* Redefine the color blue for this block only */
(polygons
  (vertices  2. 2. 0.  2.5 2.5 0.), : blue), /* Draw a blue line */ }
# This line is drawn in the original blue.
(polygons
  (vertices  2.5 2.5 0.  3. 3. 0.), : blue), /* Draw a blue line */

In all cases, names must be defined before they are referenced.

Hierarchies may be created within YAODL objects using the group object. A group object may have any number of arguments, each of which is a YAODL object. A group object may also contain properties, but each property must have a definition for each object in the group. For example:

(group V =
 (vertices -0.175000 0.350000 0.020000),
N =
 (normals 0.000000 0.000000 1.000000),
I =
 (indices 0 1 2),
half = (indexpolygons V, I, : N), half,
(group half,
 : (rotates 180.000000 0.000000 0.000000 1.000000),
),
),

As previously mentioned, objects within a YAODL file may also be stored using a binary format. Binary YAODL objects start with an @ character followed by a NULL-terminated ASCII string identifying the name of an object. Valid object names are:

colors regularMesh
contours rotates
indexpolygons scales
indices texcoords
group textures
normals translates
nurbs trimcurves
polygons vertices

Following the object name string is an 8-byte integer specifying the number of bytes of binary data that follow. The format of the binary data depends on the type of data used by the object. Integer and floating-point data are stored normally, using the native byte order of the machine. Indices are stored using the following format:

'@'  "indices" number_of_bytes number_of_lists lengths[number_of_lists] data

The number_of_lists specified is an integer indicating how many arguments (groups of integers) the object has. The array length is a list of integers specifying the length of each group of integers. Following this array is the integer data for each list.

The following is an example of a small YAODL file that renders a cube:

#YAODL
v =
(vertices 0.250000 -0.250000 -0.250000 0.250000 0.250000 -0.250000
-0.250000 0.250000 -0.250000 -0.250000 -0.250000 -0.250000
0.250000 0.250000 0.250000 0.250000 -0.250000 0.250000
-0.250000 0.250000 0.250000 -0.250000 -0.250000 0.250000 ,),
i =
(indices
0 1 2 3 ,
0 1 4 5 ,
4 1 2 6 ,
7 6 2 3 ,
0 5 7 3 ,
7 6 4 5 ,
)
,
(indexpolygons v,
i,
: (colors 1.000000 1.000000 0.400000 0.700000 0.500000 0.200000
0.000000 0.000000 1.000000 0.300000 1.000000 1.000000
0.200000 1.000000 0.700000 1.000000 0.700000 0.700000 ,),
(normals 0.000000 0.000000 -1.000000 1.000000 0.000000 0.000000
0.000000 1.000000 0.000000 -1.000000 0.000000 0.000000
0.000000 -1.000000 0.000000 0.000000 0.000000	1.000000
,),
),

For Further Information

For further information about YAODL, see the YAODL(6D) manual page found on the Silicon Graphics system. For more information, contact:

Silicon Graphics Inc.
Attn: Visual Magic Marketing
2011 North Shoreline Blvd.
Mountain View, CA 94039-7311
Voice: 800-800-4SGI
FTP: ftp://sgi.com/
WWW: http://www.sgi.com/


This page is taken from the Encyclopedia of Graphics File Formats and is licensed by O'Reilly under the Creative Common/Attribution license.

More Resources