[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