NAME

       XRacer::BlenderImport - Import files exported by xracer-blenderexport.py

SYNOPSIS

         use XRacer::BlenderImport;

         $world = parse XRacer::BlenderImport [ $filename ];

         $index = $world->add_vertex ($vertex);
         $verticesref = $world->get_vertices;
         %layerinfo = $world->get_layer_info;

         @objects = $world->get_meshes_in_layer ($layer);

DESCRIPTION

       The "XRacer::BlenderImport" module contains functions for importing special XRacer-
       specific Blender files into Perl scripts.  These Blender files have been previously
       exported by the "xracer-blenderexport.py" Python script for Blender.

       The "XRacer::BlenderImport" module parses the "blender.export" file, cleans it up
       (removing multiple vertices, for example) and presents an internal world representation.
       The world is divided into layers (corresponding to the layers in the original Blender
       image), and in each of these layers is a set of meshes.

   FUNDAMENTAL TYPES
       Vertices are stored in a global list, so that common vertices are only stored once. A
       vertex structure looks like this:

         $vertex = { coords => [ $x, $y, $z, 0 ],
                     texcoords => [ $u, $v ],
                     normal => [ $nx, $ny, $nz, 0 ],
                     colour => [ $r, $g, $b, $a ] };

       The fields are (in order): the coordinates of the vertex, the texture coordinates, the
       normal vector at this point and the colour of the vertex.

       Faces are stored simply as a list of vertex indices (relative to the global list of
       vertices). A face looks like this:

         $face = { vertices => [ $index0, $index1, $index2, ... ] }

       Faces have at least three vertices, and maybe more.

       A mesh is a list of faces and additional information, such as the name of the mesh
       (object). A mesh structure looks like this:

         $mesh = { name => $name,
                   layer => $layer,
                   faces => \@faces,
                   material => [ $red, $green, $blue ],
                   has_colours => $has_colours,
                   has_texcoords => $has_texcoords,
                   has_material => $has_material };

       The fields are: the name of the mesh (or object), the layer on which the object exists,
       the list of faces, the material and then three flags which are passed to us from Blender:
       did the user supply vertex colours? did the user supply texture coordinates? and did the
       user supply a material?

CLASS METHODS

       $world = parse XRacer::BlenderImport [ $filename ];
           Parse the import file $filename (or "blender.export" if no filename is given) and
           generate a world representation.  If the file could not be parsed, then this function
           will print an error message and return "undef".

OBJECT METHODS

       $index = $world->add_vertex ($vertex)
           This function adds a single vertex to the world object (vertices are stored in a large
           shared list so that common vertices are folded into one). It returns the vertex index
           of the new vertex.  If another vertex with the same position, texture coordinates,
           normal and colour existed, then this function would return the index of the other
           vertex, rather than creating a fresh vertex object.

       $verticesref = $world->get_vertices
           This returns a reference to the global list of vertices. You must not update or change
           this list. Use the "add_vertex" method instead.

       %layerinfo = $world->get_layer_info
           This method returns a hash. The keys of the hash are layers which contain at least one
           object. The values of the hash are the number of objects in that layer.

           For example, if the world contained 3 objects on layer 1, 1 object on layer 2 and 4
           objects on layer 5, then the hash returned would be equivalent to:

             %layerinfo = ( 1 => 3, 2 => 1, 5 => 4 );

       @objects = $world->get_meshes_in_layer ($layer)
           Get a list of the objects (i.e. meshes) found in layer $layer.  See the DESCRIPTION
           section above for a description of the mesh structure.

AUTHOR

         Richard W.M. Jones, <rich@annexia.org>

COPYRIGHT

       XRacer is copyright (C) 1999-2000 Richard W.M. Jones (rich@annexia.org) and other
       contributors listed in the AUTHORS file.

SEE ALSO

       perl(1), xracer(6).