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.

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.

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:

You must first specify a model, then the next thing must be your first object. At that point you can define that particular object by any other command. You can only have 1 model per file, but as many objects to make up that model as you want.
A "cn" or "acn" can only happen at the begining of a type- definition. This may seem strange, but what it boils down to is that once you have started defining a particular type of primitive, you can only place "cn" or "acn" from the begining to the first vertex.
A "n" can be placed anywhere inside a type-definition, however if you specify an "act*" command, you are restricted to before the first vertex. If you put a normal after the first vertex, it will get over- written when the triangles are computed.
On the other hand, "co" color changes can happen anywhere inside an object declaration.
Once you declare a model name, the next command must be the declaration of an object. Comments are okay.
Vertex definitions, "v", must occur inside of a "type" definition.
Push, pop, rot, and tra can only be called _outside_ of a type-definition. This is a necessary evil and may at first seem to be limiting, but it is a rare thing that you need to translate or rotate while defining, for instance, a polygon.
When using "act2" or "act4" you should be very careful with your normals. Passing "acn" to the "act*" functions will take care of the normals for you. "act2" will create a normal for each triangle. "act4" will create normals for each triangle and additionally average all the normals for the center vertex. You must take into account how the 4 vertices are being broken up into triangles if you wish to specify your own normals. It is suggested that you let the "act*" functions handle it for you. Note that you can only use "n" or "cn" (not "acn") if you are specifying your own normal and then only before the first vertex is defined. Both "act*" functions overwrite anything at the first vertex or after.

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_