GLASS object file specification

Index
  • Index
  • How GLASS reads an object file
  • Options in a GLASS object file
  • Components of a GLASS object
  • Textures
  • Materials
  • Triangle Lists
  • Variables
  • Active Points
  • Components
  • Structure
    •
  • A complete GLASS object
  • About this document

    • 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):
  • texture
  • material
  • triangle_list
  • variable
  • active_point
  • component
  • 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 object

     There are 7 component types in a GLASS object, which are defined between a begin/end pair. These are:
  • Textures
  • Materials
  • Triangle Lists
  • Variables
  • Active Points
  • Components
  • 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 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). 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

    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. 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 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:
  • 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 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.

    Back to index

    Robert Cleaver Ancell
    Last modified: Fri Jun 29 17:44:47 NZST 2001