# GLASS model file specification

## Index

- Index
- How GLASS reads a model file
- Options in a GLASS model file
- Components of a GLASS model
- Textures
- Materials
- Surfaces
- Variables
- Active Points
- Nodes
- Structure
- A complete GLASS model
- About this document

GLASS models are stored in plaintext files, using the following format.

## How GLASS reads a model file

GLASS reads the model file by breaking it into words. A word is a continuous string of non-whitespace characters surrounded by whitespace, or a string of characters surrounded by double quotes ("). The double quotes do not count towards the word. For example if a GLASS model file contained the line:

> `

>     foo
>     bar  "foo bar"

> `

GLASS would read this as three words, `foo', followed by `bar', and `foo bar'.

Comments are started by the hash character (#), and a terminated by the next newline. Comments are completely ignored by GLASS. For example:

> `

>     # A comment
>     begin something # Another comment
>       # More comments
>     end

> `

GLASS would read this as:

> `

>     begin something
>     end

> `

## Options in a GLASS model file

The following fields are read from the file:

### name

The name of this GLASS model. Followed by a string. Default is "". Optional.

### version

The version of GLASS this model is designed for. Followed by a string. Example "1.0.0". If the version of GLASS that is loading the model differs from this, a warning is emitted. Optional.

### begin

Begins a component of a GLASS model. Followed by a string that can be (case sensitive):
- texture
- material
- surface
- variable
- active_point
- node
- structure
Explained in detail below. At least some of these will be required.

### end

Ends the last GLASS component. (see above). Each begin must be followed by an end.

## Components of a GLASS model

There are 7 component types in a GLASS model, which are defined between a begin/end pair. These are:
- Textures
- Materials
- Surfaces
- Variables
- Active Points
- Nodes
- Structure

### Textures

Textures are used to load RGB image files and use them as (openGL) textures. The texture component has two fields, these are:

#### name

The name of the texture, must be unique. Required.

#### image

This field is the path of a RGB image file relative to the GLASS model file. Required.

An example of a texture component is:

> `

>     begin texture
>       name		"marble texture"
>       image		"textures/marble.rgb"
>     end

> `

This defines a new texture with the name "marble texture", that uses the image file "marble.rgb" which is found in the the subdirectory "textures/" which is in the directory the GLASS model is in.

### Materials

Materials define the lit properties, and the texture used by triangles in the GLASS model. A material component has seven fields. These are:

#### name

Defines the name of the material. Must be unique. Required.

#### texture

The name of a texture component. If the material has this field, then a texture will be used by triangles that use this material. Optional.

#### ambient

The ambient reflectance of the material. Followed by four floating point values that define the ambient RGBA reflectance. If unused, the material has an ambient reflectance of (0.2, 0.2, 0.2, 1.0). Optional.

#### diffuse

The diffuse reflectance of the material. Followed by four floating point values that define the diffuse RGBA reflectance. If unused, the material has an diffuse reflectance of (0.8, 0.8, 0.8, 1.0). Optional

#### specular

The specular reflectance of the material. Followed by four floating point values that define the specular RGBA reflectance. If unused, the material has an specular reflectance of (0.0, 0.0, 0.0, 1.0). Optional

#### emission

The emitted light intensity of the material. Followed by four floating point values that define the RGBA emitted intensity. If unused, the material has an emission of (0.0, 0.0, 0.0, 1.0). Optional

#### shininess

Followed by a singe floating point value that defines the RGBA specular exponent of the material. If unused, material has a shininess of 0.0. Optional

An example of a material is:

> `

>     begin material
>       name		"blue marble"
>       texture	"marble texture"

>       ambient	0.1 0.1 0.8 1.0
>       diffuse	0.1 0.1 0.8 1.0
>       specular	1.0 1.0 1.0 1.0
>       emission  	0.0 0.0 0.0 1.0
>       shininess   	10.0
>     end

> `

### Surfaces

A surface defines a solid piece of the GLASS model. It has one field, its name, and a list of triangles.

#### name

The name of the surface. Must be unique. Required.

### Triangles

Triangles are defined between braces ({, }). A triangle has six fields. These are:

#### material

The name of a material component used by this triangle. Optional

#### pos

The position of a vertex in the triangle. It is followed by an integer value that defines which vertex this is changing (0-2), and three floating point values that define the position of that vertex. The default position is (0.0, 0.0, 0.0). Optional (but highly recommended!).

#### col

The colour of a vertex in the triangle. It is followed by an integer value that defines which vertex this is changing (0-2), and three floating point values that define the RGB colour of that vertex. The colour field is only used when lighting is disabled. The default colour is (1.0, 1.0, 1.0). Optional

#### alpha

The alpha colour component of a vertex in the triangle. It is followed by an integer value that defines which vertex this is changing (0-2), and a floating point value that define the alpha colour of that vertex. The alpha field is only used when lighting is disabled. The default alpha component is 0.0. Optional.

#### nor

The normal of a vertex in the triangle. It is followed by an integer value that defines which vertex this is changing (0-2), and three floating point values that define the normal of that vertex. The normal field is only used when lighting is enabled. The default value is (0.0, 0.0, 1.0). Optional

#### tex

The texture co-ordinate of a vertex in the triangle. It is followed by an integer value that defines which vertex this is changing (0-2), and two floating point values that define the 2D texture co-ordinate of that vertex. The texture co-ordinate field is only useful if the triangles material has a texture, and texturing is enabled. The default value is (0.0, 0.0). Optional.

An example of a surface is:

> `

>     begin surface
>       name "marble pyramid"

>       {
>         material "blue marble"

>         pos 0 0.0 0.0 -5.0
>         col 0 1.0 0.0 0.0
>         nor 0 0.0 -1.0 0.0
>         tex 0 0.5 0.0

>         pos 1 4.330127 0.0 2.5
>         col 1 0.0 1.0 0.0
>         nor 1 0.0 -1.0 0.0
>         tex 1 0.9330127 0.75

>         pos 2 -4.330127 0.0 2.5
>         col 2 0.0 0.0 1.0
>         nor 2 0.0 -1.0 0.0
>         tex 2 0.0669873 0.75
>       }

>       {
>         material "blue marble"

>         pos 0 4.330127 0.0 2.5
>         col 0 0.0 1.0 0.0
>         nor 0 0.774597 0.447214 -0.447214
>         tex 0 0.9330127 0.75

>         pos 1 0.0 0.0 -5.0
>         col 1 1.0 0.0 0.0
>         nor 1 0.774597 0.447214 -0.447214
>         tex 1 0.5 0.0

>         pos 2 0.0 5.0 0.0
>         col 2 1.0 1.0 0.0
>         nor 2 0.774597 0.447214 -0.447214
>         tex 2 0.5 0.5
>       }

>       {
>         material "blue marble"

>         pos 0 0.0 0.0 -5.0
>         col 0 1.0 0.0 0.0
>         nor 0 -0.774597 0.447214 -0.447214
>         tex 0 0.5 0.0

>         pos 1 -4.330127 0.0 2.5
>         col 1 0.0 0.0 1.0
>         nor 1 -0.774597 0.447214 -0.447214
>         tex 1 0.0669873 0.75

>         pos 2 0.0 5.0 0.0
>         col 2 1.0 1.0 0.0
>         nor 2 -0.774597 0.447214 -0.447214
>         tex 2 0.5 0.5
>       }

>       {
>         material "blue marble"

>         pos 0 -4.330127 0.0 2.5
>         col 0 0.0 0.0 1.0
>         nor 0 0.0 0.447214 0.894427
>         tex 0 0.0669873 0.75

>         pos 1 4.330127 0.0 2.5
>         col 1 0.0 1.0 0.0
>         nor 1 0.0 0.447214 0.894427
>         tex 1 0.9330127 0.75

>         pos 2 0.0 5.0 0.0
>         col 2 1.0 1.0 0.0
>         nor 2 0.0 0.447214 0.894427
>         tex 2 0.5 0.5
>       }
>     end

> `

This defines a multi-coloured tetrahedron, that when lit has the material "blue marble".

### Variables

A variable controls transforms used by the GLASS model. It has four fields.

#### name

The name of the variable. Must be unique. Required.

#### value

The current value of the variable. Followed by a floating point value that defines this value. Default value is 0.0. Optional.

#### min

The minimum value the variable can take. Followed by a floating point value that defines this minimum. Default value is 0.0. Optional.

#### max

The maximum value the variable can take. Followed by a floating point value that defines this maximum. Default value is 1.0. Optional.

An example of a variable is:

> `

>     begin variable
>       name	"size"
>       min	0.1
>       max	10.0
>       value	1.0
>     end

> `

### Active Points

Active points give feedback from the current shape of the GLASS model. They have two fields.

#### name

The name of the active point. Must be unique. Required.

#### initial_dir

The initial direction that the active point points to. Followed by three floating point values that define the initial direction of the active point. Default value is (1.0, 0.0, 0.0). Optional.

An example of an active point is:

> `

>     begin active_point
>       name	      "pyramid tip"
>       initial_dir 0.0 1.0 0.0
>     end

> `

### Nodes

The nodes in a GLASS model make up the way the surfaces connect together. Nodes have six fields.

#### index

Each node needs a unique integer to link them together. Followed by one integer value. The node with the index of zero is the root node (unless a structure is defined), and the others are attached to it. Required.

#### next_index

The index of a sibling node of the current node. Followed by a single integer that is a valid index of a node. A sibling node will inherit nothing from the current node, but shares the same parent as the current node. Only required if a structure is not used. Optional.

#### child_index

The index of a child node of the current node. Followed by a single integer that is a valid index of a node. A child node inherits any transforms that are performed by the current node. Only required if a structure is not used. Optional.

#### transform

This defines the type, and parameters of an openGL basic transform. Followed by n parameters, that can be either constants, or variables. The first word after transform is the transform type (case sensitive). It can be one of:
- TRANSLATE (3)
- ROTATE (4)
- SCALE (3)
- TRANSLATE_X (1)
- TRANSLATE_Y (1)
- TRANSLATE_Z (1)
- ROTATE_X (1)
- ROTATE_Y (1)
- ROTATE_Z (1)
- SCALE_X (1)
- SCALE_Y (1)
- SCALE_Z (1)
- SCALE_EVEN (1)
The number in brackets is the number of parameters (nfor that type of transform (not part of the name).

The type is followed by n parameters, which can be a floating point constant, or a variable. Variables are used by adding "V::" to the front of the variables name.

Examples of transforms are:

> `

>     transform TRANSLATE 1.2 -2.1 3.9
>     transform SCALE_EVEN "V::scale factor"
>     transform SCALE 1.0 "V::y scale factor" 2.8

> `

#### list

The name of a surface. Followed by a valid name of a triangle list. When this node is drawn, that surface will be drawn. Optional.

#### active_point

The name of an active point. Followed by a valid name of an active point. This active point will calculate the current position and direction of the (initial) vector (0.0, 0.0, 0.0), after the transform in this node has been completed. Optional.

An example of two nodes are:

> `

>     begin node
>       index        0
>       transform    SCALE_EVEN "V::size"
>       list         "marble pyramid"
>     end

>     begin node
>       index        1
>       transform    TRANSLATE_Y 5.0
>       active_point "pyramid tip"
>     end

> `

### Structure

The structure makes a convenient way of defining how nodes link together by hand. While the next_index, and child_index fields can be used with nodes, a structure allows you to draw the shape of the tree so you can see what you're doing.

To draw the structure, convert the indices of the nodes to three character numbers, for example the index 21 would go to 021. Start by writing the index of the root node. If the root has a child, its index would go directly below it. If the root has a sibling, its index would be written to the right of the root index, with 8n-3 dashes (-), between them. (n is the number of rows across you want this index). Continue to do this for each node, building up the tree of how the nodes link together.

This is perhaps hard to explain, but easy to do in practice (see the below examples).

An example of a structure is:

> `

>     begin structure
>     000
>     001
>     end

> `

This shows that node 000 (index=0), is the root node, and node 001 (index=1), is a child of this node.

An example of a more complicated structure is:

> `

>     000
>     001---------------------013-----015
>     002-----003-----010     014     016
>     004     005     011     017     019
>     006     007     012     018     020
>     008     009             021     023
>                             022     024

> `

As you can see, this way is easier to do by hand, as you can see the "big picture" as you link the nodes together. If you had used the next_index, and child_index fields, you would be more likely to make a mistake.

## A complete GLASS model

All the above components can be written into the file in any order, although it is perhaps a good idea to stick to the above order, to keep the file logical. Collecting the examples used above, we can create a textured pyramid, with one variable that changes the size of the pyramid, and a point on the top of the pyramid that allows us to find out how high it is.

The finished model:

> `

>     # An example of how to create a GLASS model
>     # A textured pyramid, with a variable to change the size, and
>     # an active point to find the height of the pyramid.
>     #
>     # See glass.sourceforge.net for details
>     name    "pyramid"
>     version "1.2.0"

>     # The texture used by the pyramid
>     begin texture
>       name		"marble texture"
>       image		"textures/marble.rgb"
>     end

>     # The material used by the surfaces of the pyramid,
>     # uses the above texture
>     # It's a blue colour
>     begin material
>       name		"blue marble"
>       texture	"marble texture"

>       ambient	0.1 0.1 0.8 1.0
>       diffuse	0.1 0.1 0.8 1.0
>       specular	1.0 1.0 1.0 1.0
>       emission  	0.0 0.0 0.0 1.0
>       shininess   	10.0
>     end

>     # The triangles that make up the pyramid
>     begin surface
>       name "marble pyramid"

>       {
>         material "blue marble"

>         pos 0 0.0 0.0 -5.0
>         col 0 1.0 0.0 0.0
>         nor 0 0.0 -1.0 0.0
>         tex 0 0.5 0.0

>         pos 1 4.330127 0.0 2.5
>         col 1 0.0 1.0 0.0
>         nor 1 0.0 -1.0 0.0
>         tex 1 0.9330127 0.75

>         pos 2 -4.330127 0.0 2.5
>         col 2 0.0 0.0 1.0
>         nor 2 0.0 -1.0 0.0
>         tex 2 0.0669873 0.75
>       }

>       {
>         material "blue marble"

>         pos 0 4.330127 0.0 2.5
>         col 0 0.0 1.0 0.0
>         nor 0 0.774597 0.447214 -0.447214
>         tex 0 0.9330127 0.75

>         pos 1 0.0 0.0 -5.0
>         col 1 1.0 0.0 0.0
>         nor 1 0.774597 0.447214 -0.447214
>         tex 1 0.5 0.0

>         pos 2 0.0 5.0 0.0
>         col 2 1.0 1.0 0.0
>         nor 2 0.774597 0.447214 -0.447214
>         tex 2 0.5 0.5
>       }

>       {
>         material "blue marble"

>         pos 0 0.0 0.0 -5.0
>         col 0 1.0 0.0 0.0
>         nor 0 -0.774597 0.447214 -0.447214
>         tex 0 0.5 0.0

>         pos 1 -4.330127 0.0 2.5
>         col 1 0.0 0.0 1.0
>         nor 1 -0.774597 0.447214 -0.447214
>         tex 1 0.0669873 0.75

>         pos 2 0.0 5.0 0.0
>         col 2 1.0 1.0 0.0
>         nor 2 -0.774597 0.447214 -0.447214
>         tex 2 0.5 0.5
>       }

>       {
>         material "blue marble"

>         pos 0 -4.330127 0.0 2.5
>         col 0 0.0 0.0 1.0
>         nor 0 0.0 0.447214 0.894427
>         tex 0 0.0669873 0.75

>         pos 1 4.330127 0.0 2.5
>         col 1 0.0 1.0 0.0
>         nor 1 0.0 0.447214 0.894427
>         tex 1 0.9330127 0.75

>         pos 2 0.0 5.0 0.0
>         col 2 1.0 1.0 0.0
>         nor 2 0.0 0.447214 0.894427
>         tex 2 0.5 0.5
>       }
>     end

>     # A variable to control the scale of the pyramid
>     begin variable
>       name	"size"
>       min	0.1
>       max	10.0
>       value	1.0
>     end

>     # An active point to get the height of the pyramid
>     begin active_point
>       name	      "pyramid tip"
>       initial_dir 0.0 1.0 0.0
>     end

>     # The nodes
>     # Scale the pyramid, and draw it
>     begin node
>       index        0
>       transform    SCALE_EVEN "V::size"
>       list         "marble pyramid"
>     end

>     # Translate up to the top of the (unscaled) pyramid, and put
>     # an active point there. (This node will inherit the
>     # scale transform from the above one).
>     begin node
>       index        1
>       transform    TRANSLATE_Y 5.0
>       active_point "pyramid tip"
>     end

>     # How the nodes link together
>     # Could have done this in the definitions of each node,
>     # but since writing this by hand, it's easier this way
>     begin structure
>     000
>     001
>     end

> `

## About this document

If you think that parts of this document could be explained better, and you are able to do so, then please email me with improvements. If you make a GLASS model, consider adding it to an archive of them (under a suitable free license), by mailing it to me. All (and any) feedback is welcome.

Back to index

Last modified: Thu Dec 12 13:39:42 NZDT 2002