Documentation for
Prodigal VRML Viewer
- an OpenGL based VRML viewer
Table of Contents
Preface
This is a quick update of the documentation for the Prodigal VRML viewer.
Last time, Lars J. did all the documentation for a program he hadn't
written anything but the source file heading template for. Mostly
because I, Peder, am much too lazy to document anything I do.
Nobody will probably read this anyway so I will just go blah, blah, blah
for the rest of the documentation.
Prodigal VRML viewer is a viewer for VRML V1.0 and VRML V2.0 files.
All VRML V1.0 and most VRML V2.0 nodes are supported.
The VRML viewer now includes our very own file requester. Since both
Lars and I are old Amiga geeks, we like a file requester to be
small and simple, but above all: It should be fast to browse through
the file system; no popup menu to go to the parent directory or
stuff like that. Other features include a file filter and a separate
thread is started to find file attributes (icon and filename).
The filerequester is still very Beta, but in the furure we expect to
release the requester in a shared library to enable other developers
to use it too.
A word about bug-reporting: We have tested the viewer
with lots of objects, but we am pretty sure there are still some
bugs. If you find an object that isn't rendered correctly I would
appreciate it a lot if you could mail me the object, or give me a
pointer to where I can download it.
You can send bug-reports to
<pederb@sim.no>.
Start vrmlview either from the Terminal, or by launching it from the
Tracker by double-clicking or dropping a vrml file on the icon.
You can at any time load new objects by dropping files onto the window.
After a file is loaded, the window may look something like this:
Venus-like VRML object
Object Movement
Prodigal VRML Viewer is designed for three button mice, but BeOS will
let you emulate the middle - and for the even more mousially challenged -
the right mouse button if needed. I think it is Ctrl &
Option and Ctrl & Command that are the
magic key combinations.
The left mouse button is used for object rotation. It should be fairly
logical how to move the mouse to get the object positioned the way you
want. One hint that can be useful: it's easiest to rotate the object
around the Z-axis by dragging the mouse along the window's edges.
The middle mouse button is for moving the object around on the
XY-plane to position the object in the window.
The right mouse button is for moving the object along the Z-axis
(zooming).
The File menu
Save snapshot
Here you can save a snapshot of the current view. When this menu item
is selected, you will be presented with a file dialog which lets you
choose a file name for the snapshot. Here you will be presented with our
fantastic new file requester. Since the BeOS file requester sucks,
we made our own :-) The snapshot can be saved as
either a JPEG or PNG file. You can select your preferred file format
in the Settings menu.
Add model...
Add a new model from disk. The requester once again.
Refresh model
Reload the currently shown model from disk. This is meant to be used during
model development for quickly updating the viewer without needing any
file requester interaction.
Next model
Show next model in list of currently loaded models.
Previous model
Show previous model in list of currently loaded models.
Remove model
Remove currently shown model from memory, freeing up resources.
Quit
Exit viewer.
The View menu
Information
This menu item will toggle on/off various information about the
object. This includes information about the various geometric
primitives used to build the model, in addition to the distance from
the current viewpoint to the center of the object.
Flatshading
This menu is used to toggle flatshading on/off. Flatshading can be
useful to visualize polygons more clearly; in addition, turning on
flatshading may lead to faster rendering.
Normals
Activate this menu item if you want to view the normals at each
vertex/polygon.
Boundingboxes
By activating this item, a boundingbox will be drawn around every
geometric primitive in the model.
Wireframe
By activating this menu item, all the polygons in the model will be
outlined. The color and width of the lines can be adjusted from
the Settings menu.
Vertices
When this menu item is activated, all vertices in the model will be
drawn. The color and size of each vertex can be adjusted in the
Settings menu. Be aware though: The BeOS GL team forgot to remove
a debug message when drawing a vertex. For each vertex drawn, the
debug message "__glRenderAliasedPointN" will be written to stderr,
causing the rendering to slow down a lot.
Filled
This will turn on/off filling of the polygons.
Hidden parts
When rendering without polygon filling, you can enable this menu item
to draw the model with hidden lines, vertices and normals.
Textures
If there are any textures in the model, you can turn on texturemapping
by activating this menu item. Texture mapped objects may need much
longer to render than non texture mapped objects, depending on your
computer model, your graphics redndering system and your OpenGL
driver.
One boundingbox when moving
If this menu item is activated, the viewer will only draw a
boundingbox (encapsulating the whole object) when you rotate, zoom or
translate the object. This can be useful on large objects with
thousands of polygons as it enables you to smoothly manipulate such
objects.
Boundingboxes when moving
When this menu item is selected, the viewer will draw a bounding box
around every geometry node in the model when you rotate or translate
the object.
Full model when moving
When activated, this will enable you to move the model with all the
geometry enabled.
Textures off when moving
If this item is enabled texturemapping will not be kept on when you
rotate or translate the object. This is recommended unless you
have special texture hardware or a very fast computer.
Two side lighting
This submenu is needed to correctly view some faulty models. Some
models specify a known vertex ordering for its face sets even though
the vertex ordering may vary from polygon to polygon. You should try
to set this submenu to 'On' whenever the shading looks incorrect for a
model. That is; if some polygons seem to be much darker than its
coincident polygons. In some rare cases, it can also be useful to set
two side lighting to 'Off'. For instance when you have got a partly
transparent object, but you don't want the back facing polygons to be
light shaded.
For most models this menu should be left at 'Auto'.
Backface culling
When backface culling is enabled, all back facing polygons will not be
drawn. This will lead to increased performance on most
models. Correctly implemented VRML models will specify when backface
culling should be turned on or off, so this submenu should be left at
'Auto' for most of the time. For models that seem to be slow to
render, you could try to set this submenu to 'On'. If a model seems to
lack some of its polygons, you could try to set backface culling to
'Off', this will make sure that all polygons will be drawn every time.
Vertex ordering
If the shading for a model looks completely wrong; if all the polygons
are dark even when faced directly towards a light source, you should
try to select a vertex ordering other than 'Auto'. You should try to
set two side lighting to 'On' before experimenting with the vertex
ordering, since when vertex ordering is set to somthing other than
'Auto', all the polygons in all the face sets will get the same vertex
ordering.
The Settings menu
This menu enables you to set some preferences for the viewer.
- Line width. Use this submenu to set the width of the lines
(in screen pixels) used to
draw the models in wireframe mode.
- Vertex size.
Use this to specify the size of the point (in pixels) used to draw the
vertices in the model.
- Background color.
The background color will initially be dark
blue. If you don't like this background color, you can select another
using this submenu.
- Line color.
With this menu you can select the color of the lines used to outline
the polygons when you select wireframe mode at the same time as
polygon fill is on.
- Vertex color.
This is the color used to draw the vertices when vertex drawing is
active at the same time as polygon fill.
- Render quality.
This menu controls the quality of the rendering
done by OpenGL (or Mesa). More specifically, it controls whether
antialiasing (for point, lines and polygons), perpective correction
(for color and textures) and linear interpolation for textures is
turned on or off. The render quality will initially be set to "Don't care".
Your OpenGL implementation will then use its prefered settings. Set this to
"Faster" if you want faster rendering, and to "Nicest" if you want the
best render quality at all times.
- Snapshot type.
This setting is used to set the file format of the
snapshot. You can save a snapshot of your model by selecting
"Save snapshot" in the File menu.
- Transparency. Use this submenu to set the strategy used to draw
transparent objects. BeOS PR2 has a bug in glPolygonStipple so screendoor
transparency will not work in PR2, and probably not in PR3 either.
The Cameras menu
All the cameras specified in the VRML file will be presented to you in
this menu. In addition the viewer will always create a camera which is
placed in front of the object. By selecting a camera the current
viewpoint is moved to the viewpoint of that camera. All the rotation
and translation done on the object will be reset.
The Lights menu
This menu will contain all the lights which were specified in the VRML
file. The viewer will also add a directional light source,
illuminating the object from above and to the left. All lights
(except the original directional light) will initially be turned
off. You can toggle the on/off state of a lightsource by selecting it
from this menu.
This viewer contains the following limitations:
- only local resources are loaded, e.g. no html- or ftp-fetching is
done.
- no dynamic behaviour of VRML 2.0 models is being used, i.e. no
sensor activation, no interpolation, no scripting, no movie textures.
- no collision detection support on VRML2.0.
- VRML2.0 Fog and Background nodes not supported.
- no sound support for VRML2.0 models.
Check our web-site at http://www.sim.no for future upgrades which
might remove any of these limitations.
Here are a couple of links to places you can find information about VRML
and more VRML objects:
The Fourth Dimension, Time, can be sliced up in a number of ways. Both
Peder and I are big fans of Douglas Adams, so I chose to slice it up the
Douglas Adams way.
The Douglas Adams way goes like this: You start in the present, moving
forwards into the future. After going into the future for a while, you
suddenly jump backwards in time, far into the past, and work yourway
forwards to the present again. After that it becomes very fuzzy, with
lots of eddies in time and some improbability stuff. I figured I should
stop just before we're back in the present again. Sounds like a lot of
fun, doesn't it? Well, even if Douglas Adams made it fun - who do I
think I am?
The Future
Besides fixing bugs and reading postal cards of course (see
license section), the author will spend time
on, among other stuff, these items in particular:
- Support for Be Datatypes for picture loading. For the moment I
only support JPEG, PNG and RGB.
- Support for VRML V2.0 interaction and animation.
- I have actually started on the implementation of a ray-tracer
directly linked to the VRML viewer. Soon you will be able to ray-trace
your VRML objects!
- Some multipass special effects have been implemented: Scene
antialiasing, Depth of Field and Motion blurring. Unfortunately, due
to a bug in BeOS' GL implementation, these could not be included in
this release. As soon as BeOS patch up their OpenGL implementation you
will see these effects.
- Support for other file formats. DXF and 3DS.
The Past
- v0.7 Beta:
First release.
- v0.8 Beta:
Quick bugfix release that actually introduced a couple of new bugs.
How strange... I hope very few downloaded this version.
- v0.9 Beta:
Quick bugfix release that fixed some of the bugs introduced in v0.8.
Also some new features.
- v0.95:
New features and some bugfixes.
- v1.0
Current release. Now with VRML V2.0 and lots of new features.
Prodigal VRML Viewer is copyright © 1997 by Norsk Simulator Senter
<pederb@sim.no>.
All rights reserved.
Prodigal VRML Viewer may not be used for any
commercial purposes, unless an agreement with Norsk Simulator
Senter has been made.
Permission is granted to download, uncompress, untar, install,
execute, move, rename, trash, and delete Prodigal VRML Viewer.
No warranty is made for this software - all usage is done at
ones own risk.
Postcard-ware
Prodigal VRML Viewer is postcard-ware. That means; if you like
what you see, send a postal card
(an email would be way too easy) to
Peder Blekken
Selsbakk Øvre 5
N-7027 Trondheim
NORWAY
and express your appreciation... You know that such a gesture will
make Peder's day and give him inspiration to put down even more
AM hours into working on improving the Prodigal VRML Viewer.
Big thanks must fly out to:
- Lars J. Aas. Great friend, and programmer of the intro window, the file requester filter
and probably some other stuff which I can't seem to remember right now.
- Morten Eriksen. Programmer of the VRML V2.0 file parser.
[Documentation was mostly scribbled down by Lars J]