GLASS model file specification

Index

Index

How GLASS reads a model file

Options in a GLASS model file

Components of a GLASS model

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

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.

children

The indicies of children nodes of the current node. Followed by a n integers that are valid node indicies. 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

surface

The name of a surface. Followed by a valid name of a surface. 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"
  surface      "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 children field 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 children field, 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"
  surface      "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

Robert Cleaver Ancell

Last modified: Thu Mar 13 10:43:43 NZDT 2003