GLASS object file specification
Index
GLASS objects are stored in plaintext files, using the following format.
How GLASS reads an object file
GLASS reads the object 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 object 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 object file
The following fields are read from the file:
name
The name of this GLASS object. Followed by a string. Default is "". Optional.version
The version of GLASS this object is designed for. Followed by a string. Example "1.0.0". If the version of GLASS that is loading the object differs from this, a warning is emitted. Optional.begin
Begins a component of a GLASS object. Followed by a string that can be (case sensitive):end
Ends the last GLASS component. (see above). Each begin must be followed by an end.Components of a GLASS object
There are 7 component types in a GLASS object, 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 object 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 object is in.
Materials
Materials define the lit properties, and the texture used by triangles in the GLASS object.
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). Optionalspecular
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). Optionalemission
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). Optionalshininess
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. OptionalAn 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
Triangle Lists
A triangle list defines a solid piece of the GLASS object. It has one field, its name, and a list of triangles.name
The name of the triangle list. 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. Optionalpos
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). Optionalalpha
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). Optionaltex
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 triangle list is:
begin triangle_list
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 object. 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 object. 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
Components
The components in a GLASS object make up the way the triangle lists connect together. Components have six fields.index
Each component needs a unique integer to link them together. Followed by one integer value. The component with the index of zero is the root component (unless a structure is defined), and the others are attached to it. Required.next_index
The index of a sibling component of the current component. Followed by a single integer that is a valid index of a component. A sibling component will inherit nothing from the current component, but shares the same parent as the current component. Only required if a structure is not used. Optional.child_index
The index of a child component of the current component. Followed by a single integer that is a valid index of a component. A child component inherits any transforms that are performed by the current component. 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: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 triangle list. Followed by a valid name of a triangle list. When this component is drawn, that triangle list 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 component has been completed. Optional.An example of two components are:
begin component
index 0
transform SCALE_EVEN "V::size"
list "marble pyramid"
end
begin component
index 1
transform TRANSLATE_Y 5.0
active_point "pyramid tip"
end
Structure
The structure makes a convenient way of defining how components link together by hand. While the next_index, and child_index fields can be used with components, 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 components to three character numbers, for example the index 21 would go to 021. Start by writing the index of the root component. 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 component, building up the tree of how the components 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 component 000 (index=0), is the root component, and component 001 (index=1), is a child of this component.
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 components together. If you had used the next_index, and
child_index fields, you would be more likely to make a mistake.
A complete GLASS object
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 object:
# An example of how to create a GLASS object
# 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.0.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 triangle_list
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 components
# Scale the pyramid, and draw it
begin component
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 component will inherit the
# scale transform from the above one).
begin component
index 1
transform TRANSLATE_Y 5.0
active_point "pyramid tip"
end
# How the components link together
# Could have done this in the definitions of each component,
# 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 object, consider adding it to an archive of them (under a suitable free license), by mailing it to me. All (and any) feedback is welcome.Robert Cleaver Ancell Last modified: Fri Jun 29 17:44:47 NZST 2001