[Contents]

V3D Format

Introduction

The V3D model file format is a 3D hybrid model format, which can contain data inserted and read by third party programs. The format is plain text and formatted so that viewing/editing with a text editor is possible. However for added convience, the library libv3d is available for any program to load and save V3D format data.

Layout

The base V3D file format has a data block structured layout, significant portions are separated by begin_whatever and matching end_whatever pairs. Third party hybrid data can exist both within and outside of these bounds.

When third party data is found outside of a data block, it is loaded into memory and interprited as a model but not a type the base V3D format recognizes. When third party data is found inside a data block (ie in a header or a model) then it is loaded as a comment primitive.

For examples in this document, we will label V3D specific data in green and third party data in blue. Below is a short example of a V3D file:


begin_header
author Da Demo Maker
texture_base_directory /usr/share/mytextures/
wm_icon doggypic
end_header

# This is extranous data, and since outside of
# block bounds it will be loaded as a proprietery
# model type.

begin_model standard
color 0.3 1.0 0.0 1.0  1.0 1.0 1.0 0.1 0.0
begin_quads
 normal 0.000000 0.000000 1.000000
 -2.160000 5.544000 1.224000
 0.936000 5.760000 1.440000
 1.080000 1.872000 1.224000
 -2.376000 1.800000 1.224000
end_quads
# This is a comment within a data block, it will
# be saved as a comment primitive on the model
# named "standard".
end_model standard

Block Bounds

The following statements mark the beginning and end of different data blocks. Remember that third party data found outside of a known data block will be loaded as one model marked as third party type.

begin_header (and end_header) define the V3D file header. This should be the first V3D data block in the file.

begin_model <name> (and end_model) define a V3D model. You can specify one or more in a V3D file. Each should have a different name, the first one is (by tradition) named standard.

Header Items

Header items are found within a begin_header and end_header block. The following are a list of header items and their syntax.

version <major> <minor> specifies the V3D model file version (release number is always ignored). This number should always match the version of the libv3d that generated this file.

author <name> specifies the user that made this V3D model file.

creator <name> specifies the program that generated this V3D model file.

texture_base_directory <path> specifies the texture base directory which must be an absolute path (or a path not containing the drive prefix if used on Windows). This item must come before any occurance of texture_load. The program handling this item may choose to ignore this value and impose its own texture base directory.

heightfield_base_directory <path> specifies the heightfield base directory which must be an absolute path (or a path not containing the drive prefix if used on Windows). The program handling this item may choose to ignore this value and impose its own heightfield base directory.

texture_load <name> <path> <priority> loads the specified texture <path> with the given <priority> (from 0.0 to 1.0, where 1.0 is the highest). If the given <path> is a relative path then the texture_base_directory will be prefixed to it. The <name> is an arbitary name used to referance this texture which can later be used to match this in a list of textures.

color <name> <r> <g> <b> <a> <ambient> <diffuse> <shininess> <emission> specifies a preset color specified by <name> who's values are those given. Implementation of this not complete as of this writing.

Model Primitives

Model primitives are found within a begin_model <name> and end_model block. The following are a list of model primitives and their syntax (reffer to the OpenGL definations for value characteristics of these primitives). Also note that it is entirly up to the program interpriting this data to define the standards, therefore OpenGL standards and meaning for these values may not always apply (everything here is arbitary).

translate <dx> <dy> <dz> specifies to push a matrix and translate all primitives by the given values that exist after this primitive but before the next untranslate primitive (if any). Translation matrixes are always returned to level 0 at each end_model.

untranslate undoes a level of translation from a translate primitive that occured prior.

rotate <dh> <dp> <db> specifies to push a matrix and rotate all primitives by the given values that exist after this primitive but before the next unrotate primitive (if any). Rotation matrixes are always returned to level 0 at each end_model.

unrotate undoes a level of rotation from a rotate primitive that occured prior.

begin_points (and end_points) marks the bounds for a series of vertex statement(s) that describe point(s).

begin_lines (and end_lines) marks the bounds for a series of vertex statement(s) that describe line segment(s).

begin_line_strip (and end_line_strip) marks the bounds for a series of vertex statement(s) that describe a line strip.

begin_line_loop (and end_line_loop) marks the bounds for a series of vertex statement(s) that describe a line loop.

begin_triangles (and end_triangles) marks the bounds for a series of vertex statement(s) that describe triange(s).

begin_triangle_strip (and end_triangle_strip) marks the bounds for a series of vertex statement(s) that describe a triangle strip.

begin_triangle_fan (and end_triangle_fan) marks the bounds for a series of vertex statement(s) that describe a triangle fan.

begin_quads (and end_quads) marks the bounds for a series of vertex statement(s) that describe quad(s).

begin_quad_strips (and end_quad_strips) marks the bounds for a series of vertex statement(s) that describe a quad strip.

begin_polygon (and end_polygon) marks the bounds for a series of vertex statement(s) that describe a polygon.

normal <i> <j> <k> specifies the normal (which may or may not be of unit length). This specification must come before the vertex in question and within the data block of begin_points, begin_lines, begin_line_strip, begin_line_loop, begin_triangles, begin_triangle_strip, begin_triangle_fan, begin_quads, begin_quad_strip, or begin_polygon.

texcoord <i> <j> <k> specifies the texcoord. This specification must come before the vertex in question and within the data block of begin_points, begin_lines, begin_line_strip, begin_line_loop, begin_triangles, begin_triangle_strip, begin_triangle_fan, begin_quads, begin_quad_strip, or begin_polygon. This statement is ignored if no texture was selected.

color <r> <g> <b> <a> <ambient> <diffuse> <shininess> <emission> specifies the new color and material values, each in the range [0.0 to 1.0] (including <shininess> which OpenGL has a different bounds for).

texture_select <name> enables texture and selects the one specified by <name>.

texture_orient_xy <x> <y> <dx> <dy> orients the texture along the XY plane, all texcoord statements following this will be ignored since the plane orientation will set the texcoords automatically.

texture_orient_yz <y> <z> <dy> <dz> orients the texture along the YZ plane, all texcoord statements following this will be ignored since the plane orientation will set the texcoords automatically.

texture_orient_xz <x> <z> <dx> <dz> orients the texture along the XZ plane, all texcoord statements following this will be ignored since the plane orientation will set the texcoords automatically.

texture_off disables texturing.

Last but not least, a vertex statement is a set of three floating point numbers <x> <y> <z> which can be specified between begin_points, begin_lines, begin_line_strip, begin_line_loop, begin_triangles, begin_triangle_strip, begin_triangle_fan, begin_quads, begin_quad_strip, or begin_polygon data blocks.

Review

V3D files can be large in size, so putting examples here is not an option. There are many examples available for tutoring purposes at http://wolfpack.twu.net/Vertex/.

Note that those examples assume that you have read or have this document handy as additional referance.

If you want to use libv3d (the V3D file IO library) then take a look at the programmer's referance man v3dintro to get started.


Back to the top

Vertex is Copyright © 2000-2001 WolfPack Entertainment