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