PluginViewer v0.9
-----------------

CONTENTS:
1 - Introduction
2 - Controls
3 - System Requirements
4 - Known Issues
5 - Non-Features
6 - Technical Notes
7 - Acknowledgements



1) Introduction

  This application is an OpenGL toy that lets you fly around a 3D landscape
in real-time. It reads the map files from the popular real-time tactical game
Myth II: Soulblighter, produced by Bungie Software, and uses an adaptive
level-of-detail triangle mesh to display these maps in a free-flight
perspective not possible using the game engine itself.

  To use the application, simply run pluginview.exe. The first time the app
is run, it will pop up a window with some brief instructions; click OK to
bypass these. It will then ask you to select Myth II.exe so that it can find
your installation of Myth II to read the Myth tag files and any third-party
plugins that you have.

  Note that you must have the large install of Myth II - PluginViewer does
not know how to read the Myth II tag files off CD-ROM if you have the small
or medium installs. If you do not have enough disk space for this option, you
may have some success viewing third-party plugins if they do not use any of
Myth II's built-in scenery. Failing that, you can turn off the draw-scenery
flag in settings.txt.


2) Controls

  When the application loads, you should see a Myth map spread out before you.
Use the mouse to look around. The A and Z keys increase and decrease the camera's
speed, and the X key brings it to a stop. The Q and E keys roll the camera left
and right. The Esc key exits the program.

  There are also a number of controls that you may use to affect the terrain
engine; holding down the Tab key will display the polygonal mesh without any
texturing (and with some lighting added so that you can see what's happening).

  Holding down the Shift key will stop the mesh from adapting to the changing
camera position, so you can get a clearer idea of how the application is
changing the terrain far away from the camera. As an example, hold down Shift
and fly up from the mesh, then turn and look down while pressing Tab as well
(you should keep the Shift key held throughout this, as if you release it the
app will recompute the terrain).

  The + and - keys increase and decrease the triangle budget allocated to the
mesh. Control + and Control - do the same, in greater increments.


3) System Requirements

  The most important requirement for PluginViewer is an OpenGL-compatible
3D accelerator card. Because the application has to throw around a lot of
highly detailed textures to render the terrain and the scenery, a video card
with 16 MB of video memory that can be split between framebuffer and texture
memory is recommended.

  AGP is strongly recommended, for transferring textures fast when the user
whips the view around quickly.

  The video card must also have a full (or highly compliant) OpenGL driver
implementation. I have only been able to test it on a Diamond V550 TNT card,
but I would anticipate severe problems running on any 3DFX or ATI accelerators.
Buy nVidia and support the OpenGL development community. :)

  If problems are experienced, you might try turning off scenery (see Advanced
Settings).

  The adaptive terrain model is quite CPU-intensive, and has been optimized to
provide 30 frames per second flying at moderate speed over a moderately-complex
map like Gimble in the Wabe. If you fly fast, more recomputation has to be
done and you may experience some performance degradation. Similarly, maps
with a lot of rough terrain like the Stair of Grief, or huge maps like Thoran's
Civil War may cause texture thrashing if you zoom out to view the whole map
at once.

  DirectInput and DirectDraw are used for mouse, keyboard and fullscreen, so
you must have at least DirectX 3 installed.


4) Known Issues

  First, let me say that PluginViewer was developed from reverse-engineering
many of Bungie's data formats with a hex editor. Without access to any kind
of specifications, it is almost impossible to make anything with guaranteed
correct performance. However, PluginViewer works successfully on about 90% of
all maps.

  There are some exceptions to this rule.

  - WWII: Recon has an error in the mesh header, where it has too many
    texture and shadow sections (36) for the reported mesh size (5x5 sections).

  - Any map with edited units that requires a special tagset in order to play
    will not be loaded correctly, as by default only the plugin that actually
	contains the map selected is activated. Notably, this includes WWII: Titans.
	
  - The hue-change and tint operations on scenery sometimes run amuck. If you
    load "Relic" you may see blue trees and shrubs. Without file-format
    specifications I cannot easily solve this problem.

  - "The Summoner" crashes the application inside the nVidia OpenGL drivers
    when I try to load it. I have no idea why.

  - Under Windows NT, occasionally the application will hang with a white screen
    upon startup. I have traced this to a call to DirectInput that sometimes
	never returns for an unknown, bizarre reason. This problem does not appear
	to occur under Windows 9x.

  For the most part, maps are displayed perfectly correctly - a minor miracle
given the amount of data in every tag that is ignored by PluginViewer. Any
results that you get successfully should be treated as a pleasant surprise. :)

  If the application doesn't perform as expected, try looking in the file
"debuglog.txt" for clues as to what went wrong.


5) Non-Features

  I do not plan to include any further features in PluginViewer, but you might
be able to convince me with a sufficiently persuasive argument. Issues that I
will not move on:

  - 3D models are not displayed by PluginViewer. The 3D model format is rather
    complicated, and I don't believe there would be a big enough payoff to justify
	the significant reverse-engineering effort required to read them.

  - You can't actually play Myth with PluginViewer. Well, duh.

  - Scenery is only displayed from one angle. While Myth's sets of bitmaps work
    well for its 45-degree camera angle, I believe the rotating views would look
	particularly bad when viewed from a freely-moving camera. Also, the bitmap-set
	format is rather complex, and difficult to disassemble without any tools to
	use as a reference.

  - Pointing the camera straight down causes the scenery to twist about madly on
    the spot. This is a problem with the concept of billboarding in general - you
	can't comb a hairy ball in three dimensions, and there is nothing I can do about
	it.

  - If you look carefully you can sometimes see the terrain moving. This is just
    a consequence of an adaptive terrain model, unfortunately. Every part of the
	model is oriented towards removing such visual artifacts, and it works
	surprisingly well most of the time.

  - I am not going to port this code to the MacOS, however I have been somewhat
    careful to write it using a self-contained Windows wrapper for OpenGL, file
	and system calls. Manus Celer Dei is investigating the possibility of writing
	a MacOS wrapper, and it may happen eventually.


6) Technical Notes

  This application was written in Microsoft Visual C++ 6.0 on Windows NT. It is about
10,000 lines of C++ code in total, roughly 40% of which is the terrain model. Most of
the rest is devoted to reading the tag files and setting up textures.

  The adaptive terrain model used is based on "ROAMing Terrain: Real-Time Optimally
Adapting Meshes", Duchaineau et al, in the Proceedings of Visualisation '97. Mark
Duchaineau's ROAM page may be found at http://muldoon.cipic.ucdavis.edu/~duchaine/terrain.html
and it has a brief description of the algorithm. For more details, read the paper.

  However, I have made several changes to this algorithm for the desired application
- notably, the view frustum is only used to cull for display and not for recomputation,
to ensure high framerates when looking around while stationary [this is more of a
Quake-like freelook view than a flight simulator, which was their target application].
There are also changes to the triangle error metric as a result.

  Myth II's colormaps are divided into 256x256 blocks, and I have chosen to leave them
as such in order that OpenGL can manage texture swapping more efficiently. However
where these textures join up, there are artifacts introduced by the bilinear filtering,
which does not interpolate from one texture to the next correctly. These artifacts
are quite difficult to notice in practice, and although there are ways of dealing with
them (border textures) they are not supported on most consumer 3D accelerators. You may
try to enable border textures in settings.txt if you feel lucky.

  Scenery is placed at an absolute Z position, and not relative to the current terrain
surface. In theory this could cause trees to poke half-out of the mesh at long distances,
but I have never noticed this being a problem. Trees moving up and down as the mesh
changed would probably be more disturbing anyway.

  The recomputation algorithm that decides when to recompute the split priority for
triangles has some issues related to one of its assumptions (that dx / d will be
constant, i.e. the camera is flying straight towards or away from the triangle in
question) which can cause triangles not to be recomputed when they should be. There is
code to detect and stop this, but the algorithm can still get wedged, especially when
the user zooms in smoothly from very high up and starts flying close above the surface.
I have not been able to find an efficient solution to this problem.

  There are a number of advanced settings stored in the generated file "settings.txt"
which may be changed if desired. Vertex morphing is probably the most fun to play with,
although interesting insights into the terrain algorithm may be obtained by turning
off scenery and cranking the target triangle count right down.


7) Acknowledgements

  Myth II and Myth II: Soulblighter are registered trademarks of Bungie Software.

  This application may be distributed in any way as long as due credit is given to
the original author (that's me, Chris Butcher). I would prefer if you kept this
readme with it. Source code to the application is available upon request.

  Thanks to Case, Jason Jones, Mange, ruiner, Manus Celer Dei and the crew at Badlands
for technical info, MacOS coding, and testing.

  This application is email-ware. If you like it, send me an email. Bon appetit!

Chris Butcher
8 November 1999
cbutcher@cs.otago.ac.nz
http://www.cs.otago.ac.nz/postgrads/cbutcher/
