3DV-Fileformat
==============
3DV is a GLView object format, for compact flexible definition of a single 3D Polyhedron.


3dv files are containing one object
The 3 object types of main interest are 

	- Shell 	a polyhedral object
	- ShellIndexed a polyhedral object with more level of indirection and group information
	- Mesh		a quadrilateral Grid surface

All lists and objects are enclosed with { and }.

The basic information in each object is the vertex field,
simply a list of 3d points.
Optional fields with similar structure are
	vertex_parameters : u,v,w  texture coordinates (parameters)
	vertex_normals	:  a normal for each vertex, used for smooth shading
	vertex_colors	: a r,g,b color value for each vertex
		
for the Shell and ShellIndexed primitives the faces field describes the
list of faces (or the individual polygons).
the format for a face is

0:	vertexcnt of face
1..n:	vertex number, (starting with 0)

All face are now concatenated together.
.E.g a tringle face using vertex 0,1,2 would be stored as
		3 0 1 2
.

A face with vertex cnt of 2 describes a single edge,
A face with vertex cnt 0 or 1 is ignored during rendering,
but all vertics still can be made visible by using the "Vertices" Renderstyle.
A face can have following faces with a negative vertexcnt, this indicates a hole face.
If such a file is imported you need to call "Tools->Triangulate" to display the object
properly.

For faces the optional fields
	face_normal	: a normal for each face, used for flat shading
	face_color	: a r,g,b color value for each face 
			(vertex colors have precedence if enabled)


So the minimal information required is the 
	vertex and faces field.

vertex_colors, vertex_normals, vertex_parameters  are optional.
If provided the length of the data should be same or large, than the length of the verex field.
if no vertex_normals are provided, GLView automatically calculates a smooth vertex normals, by averaging 
the normals of all faces, sharing this vertex. (so to have hard edges, you need to dupplicate the vertex coordinate
in the vertex list, or see the ShellIndexed	object.

vertex_parameters are optional and are used for texture mapping. using the coordinates (0 0 0) (0 1 0) (1 1 0) (1 0 0) 
for a rectangle, will map the texture image exactly one time on the rectangle. The z coordinate can have an effect,
if a arbitray 3D texture coordinate transform is moved, or if GLView starts support 3D solid textures.

Instead of texture mapping, vertex_colors can be used to product intersting color interpolation effects on surfaces.


Example of cube, with a color assigned to each face
; 3DV Version 1.0 Object
 shell {
    vertex {( -0.5 -0.5 -0.5)( 0.5 -0.5 -0.5) ( -0.5 0.5 -0.5) ( 0.5 0.5 -0.5) 
   ( -0.5 -0.5 0.5) ( 0.5 -0.5 0.5) ( -0.5 0.5 0.5) ( 0.5 0.5 0.5)}
    faces {
    4 0 2 3 1	; first face
    4 1 3 7 5	; second face ...
    4 5 7 6 4
    4 6 2 0 4
    4 2 6 7 3
    4 0 1 5 4}
    face_colors {( 1 1 0)( 0.5 1 0.4) ( 0 1 1) ( 1 0.647059 0) 
   ( 0 0 0) ( 0 0 1)}}


The vertex indices in the facelist of a Shell are indexing directly into
the vertex* arrays.

For the ShellIndex object these facelist indices are refering into the
verts field, instead of directly into the vertex* fields.

The verts is  a array of logical vertices.
The structure of a vert is
	index into vertex coordinate table
	index into vertex normal table
	index into vertex color table
	index into vertex parameter table

This level of indirection allows to have at a common xyz location verts with
different normal/parameter values indices.

The length of the vertex, vertex_normal, vertex_color, vertex_parameter lists must be at least
the size of the maximum corresponding index in the verts list.



A Mesh needs no explicit face infomation, because all face are forming a grid.

Example :

; 3DV Version 1.0 Object

 mesh {
    rows  10
    cols  20
   vertex { (x y z) ... 10*20 times }
}   

The corresponding C like declaration would be
struct Point {
	float x,y,z;
}
int rows=10;
iint cols=20;
Point mesh[rows*cols];

In GLView all objects of all types, even full VRML scene trees can be combined to a single object
of type GShell and saved to 3DV by using the TOOLS->combine command.



