H3D Documentation


Model Description Format:

model <name>

object <name>
MODEL COMMANDS

object <name>
MODEL COMMANDS

object <name>
MODEL COMMANDS

object <name>
MODEL COMMANDS
.
.
.



Model Commands:

{ <type> -- Type-Definition Begin
glBegin, <type> is one of {points | lines | line_strip | line_loop | triangles | trangle_strip | triangle_fan | quads | quad_strip | polygon | sphere | cylinder | disk | partial_disk | box}. Creates a BEGIN entry in the object list. For "{ sphere", "{ cylinder", "{ disk", and "{ partial_disk", please see their sections below (the rest should be intuitive from normal OpenGL usage).

} -- Type-Definition End
glEnd. Creates an END entry in the object list.

{ sphere -- Sphere Definition Block
For a sphere, you need to define some special commands in its definition block. Please see the sections below for: sphere and quadric.

{ cylinder -- Cylinder Definition Block
For a cylinder, you need to define some special commands in its definition block. Please see the sections below for: cylinder and quadric.

{ disk -- Disk Definition Block
For a disk, you need to define some special commands in its definition block. Please see the sections below for: disk and quadric.

{ partial_disk -- Partial_Disk Definition Block
For a partial_disk, you need to define some special commands in its definition block. Please see the sections below for: partial_disk and quadric.

sphere <radius> <slices> <stacks> -- Sphere Definition
For a sphere, you need to specify its radius, number of slices, and number of stacks. This will create a sphere based on the currently defined quadric.

cylinder <baseRadius> <topRadius> <height> <slices> <stacks> -- Cylinder Definition
For a cylinder, you need to specify its baseRadius, topRadius, height, number of slices, and number of stacks. This will create a cylinder based on the currently defined quadric.

disk <innerRadius> <outerRadius> <slices> <rings> -- Disk Definition
For a disk, you need to specify its innerRadius, outerRadius, number of slices, and number of stacks. This will create a disk based on the currently defined quadric.

partial_disk <innerRadius> <outerRadius> <slices> <rings> <startAngle> <sweepAngle> -- Partial_Disk Definition
For a partial_disk, you need to specify its innerRadius, outerRadius, number of slices, number of stacks, start angle, and sweep angle. This will create a partial_disk based on the currently defined quadric.

quadric <style | normals | orient | texture> <val> -- Quadric Definition
When defining a quadric, you should realize there is only one created. This is important because when you set it, those settings will be in effect until changed. A quadric does not have to be in a type-definition block.
style <point | line | silhouette | fill> -- Quadric Style
This allows you to define how the quadric is drawn. Point uses points, line uses lines, silhouette is really only for disks as it essentially only draws the "outside" lines (like a cookie-cutter), and fill which uses polygons.
normals <smooth | flat | none> -- Quadric Normal Computation
Setting the normals to smooth will do a nearest neighbor type averaging for computing the normal of each vertex (meaning it looks at all the surrounding planes to determine the normal for each vertex). Flat will use the current plane being drawn only to compute the normal. None will not set any normals. Using flat will be faster than smooth as there is not nearly as much computation involved. If you set none, be aware that if there were normals previous defined, they will be used.
orient <in | out> -- Quadric Normal Orientation
This setting is purely for directing the normals in or out of the object. For the sphere and cylinder, it's obvious which is in or out. For the disk and partial_disk, out is along the positive z, in is the -z.
texture <enable | disable> -- Quadric Texture Coordinate Generation
This will either enable the generation of texture coordinates or it will disable that feature. It will also enable or disable the setting GL_TEXTURE_2D. The texture coordinates generated are specific to the type of object being drawn with the quadric. You must have loaded and bound a texture and a texture object for the texture map to appear. For texture information, please see the texture map section below. Please recall you should be sure to turn off texturing when you are not using it or unpredictable side effects will ensue. Also, be aware that the quadric object is not actually created until after the closing brace, so to properly turn on and off the texturing, you should call "tex enable" before the definition of the quadric object and "tex disable" after. Of course, you'll want to optimize this depending on how many quadric textured objects you draw in a row.


v <x> <y> <z> -- Vertex Definition
glVertex, <x>, <y>, <z> are coords. Creates a VERTEX entry in the object list.

tex <mag | min | wrap_t | wrap_s | mode | bind | load | coord | enable | disable> -- Texture Map Properties
This little gem allows you to apply texture maps to your models. It works almost verbatim with the texture functions in the spec, however only specific settings are supported. Please beware, you should make use of the enable and disable feature of this command whenever you are using texture mapping. If you have applied a texture map to the model and not disabled texture afterwards, then draw a plain polygon...it will have unpredictable results.
mag <nearest | linear> -- Magnification Filter
For the magnification filter you can choose nearest or linear. See the red book for more information (or experiment around).
min <nearest | linear | nearest_mipmap_nearest | nearest_mipmap_linear | linear_mipmap_nearest | linear_mipmap_linear> -- Minification Filter
A few more options than magnification, but still clearly straight out of the function specification in the red book.
wrap_X <repeat | clamp> -- Controls wrapping in the t or s direction.
Controls how your texture map wraps inside of the coordinates specified. For instance, if you specify texture coords of 2,2 for the upper right corner of a polygon and have wrap in t and s set to clamp, you will see your texture map appear in the lower left portion of your polygon and not repeat itself. This is also straight out of the function spec.
mode <decal | modulate> -- How the Texture is Applied
Decal will just slap the texture on (with no lighting, etc) the polygon. Modulate will blend the texture with the current shading of the polygon. There are other unsupported settings available.
bind NAME -- Does a texture object binding
Searches for NAME in the current list of texture objects and performs the bind if it's found. The bind is necessary to insure you apply the correct texture map.
coord <x> <y> -- The 2d texture coords
Your mapping for texture coordinates to 3d space polygon coordinates.
enable | disable -- Duh
If you can't figure this out, stop trying to read this document.
load NAME FILENAME -- Loads a texture map
Associates "NAME" with the texture map "FILENAME". The texture maps need to be in SGI RGB format. Only 2d textures are supported.


call <defined_object_name> -- Call another defined object
Calls the display list of another object. You may only call an object which has already been defined.

render <on || off> -- Specify rendering policy for "renderModel()"
Specifies whether to render this object when "renderModel" is called. This is very useful in creating objects which are soley to build other objects. An example of this would be to create a series of "tiles" and at the bottom, create a grid of these tiles by translates, rotates, and calls.

object init -- Special object
The object called "init" (optional) is treated differently from all your other objects. It is not rendered when you call renderModel() regardless of it's "render" setting. It is only rendered when you call "initModel()". The purpose is to allow you to specify initialization commands in the h3d model, but allow you the control of when it is called.

co <r> <g> <b> -- Color Definition
glColor3f, <r>, <g>, <b> are color values. Creates a COLOR entry in the object list.

mat <front|back|front_and_back> <ambient|diffuse|specular|ambient_and_diffuse|emission> <r> <g> <b> <a>
mat <front|back|front_and_back> <color_indexes> <r> <g> <b>
mat <front|back|front_and_back> <shininess> <s>
mat <enable|disable>
These are all the combinations of parameters for the glMaterial function. Note you can only use this _outside_ of a sub-object. Creates a MATERIAL entry in the object list.

n <x> <y> <x> -- Normal Definition
Specifies a pre-computed normal. Creates a NORMAL entry in the object list.

cn <x0> <y0> <z0> <x1> <y1> <z1> <x2> <y2> <z2> -- Compute Normal
the '0' coords refer to the vertex for the vectors to computer the normal vector with, the '1' coords refer to the endpoint vertex for the right-hand vector, and the '2' coords refer to the endpoint vertex for the left-hand vector. Creates a NORMAL entry in the object list.

acn <num_vertices> -- Auto Compute Normal
Given 3 or 4 vertices following this command and listed in counter-clockwise order, it will auto-compute the normal. Creates a NORMAL entry in the object list.

act*
In either of the act commands, the 4 vertices given are assumed to be in a counter-clockwise listing. This affects the normal created (if specified).

act2 <which_coord> <diag_hi | diag_lo> [acn]
Computes 2 triangles with the diagonal either on the lowest vertex point or the highest. acn will autocompute the normals. Requires 4 vertices following it.

push -- Push Matrix
This will cause a glPushMatrix() to be called.

pop -- Pop Matrix
This will casue a glPopMatrix() to be called.

rot <rot_angle> <x> <y> <z> -- Rotation
Takes the rotation angle and which axes to rotate about.

tra <x> <y> <z> -- Translation
Takes the x, y, and z coordinates to translate to.

cull <on | off> -- Backface culling
Backface culling enable or disable command. Backface is currently determined by counter-clockwise vertex definition. However, you may change this in your own program which uses H3D...it is not advised that you do so.


Notes:



Model Comments:

SLASH-ASTERISK
At the begining of a line [only] causes a comment block to be started.

ASTERISK-SLASH
At the begining of a line [only] causes a comment block to be ended.

POUND_SIGN
At the begining of a line [only] causes a line to be commented.


Command Notation for Using the model command list:

MDL_VERTEX
glVertex3f(x,y,z)

MDL_COLOR
glColor3f(x,y,z)

MDL_BEGIN
glBegin(type).

MDL_END
glEnd()

MDL_ROTATE
glRotatef(e,x,y,z)

MDL_TRANSLATE
glTranslatef(x,y,z)

MDL_NORMAL
glNormal3f(x,y,z)

MDL_PUSH
glPushMatrix()

MDL_POP
glPopMatrix()

MDL_IGNORE
_do nothing_..._ignore_