MDLView\Movie DOCUMENTATION
---------------------------------------------------

Introduction:

MDLView and MDLMovie are two applets which allow quake model files to be directly included in a webpage. MDLView is a fully interactive java render for quake models.
MDLMovie is non-interactive. Images are generated when the applet is encountered by the browser and the user can just stop or start the animation.

Copyright stuff:

MDLView and MDLMovie may be used for no charge. MDLView and MDLMovie may be freely distributed but only under the name of MDLView and only with
aknowledgement of T. J. Grey (tjg1@ch.ic.ac.uk) as author. You may use the classes that comprise MDLView and MDLMovie but credit should be given where it is
due, particularly for classes which implement the getAuthorInfo() method. 
If you want documentation on any class or even the source then write to me. 

Installing the applets:

	The two most important files contained in the zipfile you download from this site are MDLView.jar and quake.pal. The file quake.pal is just an ascii palette file containing
the quake palette. MDLView.jar is a java archive file and contains all the java classes needed to run both MDLView and MDLMovie. You do not need to unarchive
MDLView.jar to use the applets and I would recommend you leave intact. 
If you already use java applets on your site then you should know how to proceed... except to say that the quake.pal file (and any custom palettes) should be placed in
the same directory (or a sub directory) as the jar file. 
For those how haven't used applets before: Place both MDLView.jar and quake.pal in a suitable directory on your web server. The location of these two files relative to
the html file will have to be included in all the webpages which contain the applets so take a few minuets to choose. 
  

Including the applet in a page:

The basic html tag to include an applet is: 

< APPLET 
              [CODEBASE = codebaseURL] 
              CODE = appletFile 
              [ARCHIVE = jarfile] 
              [ALT = alternateText] 
              WIDTH = pixels 
              HEIGHT = pixels 
          > 
          [< PARAM NAME = appletParameter1 VALUE = value >] 
          [< PARAM NAME = appletParameter2 VALUE = value >] 
</APPLET> 

The fields in square brackets [ ] are optional and can be left out (leave out the square brackets too!). The fields in italics should be replaced by the correct text for your
site: 

     CODEBASE: This is the URL of the MDLView.jar file. If the jarfile is in the same directory as the html page then CODEBASE tag can be left out. 
     CODE: This will either be "MDLView" or "MDLMovie" depending on which you want :) 
     ARCHIVE: This should be "MDLView.jar"... unless you unarchived the jar file in which case you can leave this tag out. 
     ALT: Text seen by people without a java enabled browser. 
     WIDTH: Width of applet in pixels 
     HEIGHT: Height of applet in pixels 
     PARAM: These will be discussed below. They are the way you tell the applet what to do and many of them MUST be included. 

PARAM Values used by both MDLView and MDLMovie

MDLView and MDLMovie are almost the same thing and most of the PARAM tags are the same. 

Obligatory: 

     PARAM NAME=MODEL VALUE= "URL of model file relative to the html page" 
          The URL of the model file relative to the HTML page. I usually put the .mdl file in the same directory as the html page but you do not have to. However
          you do have to put the in a sub-directory of the directory containing the webpage.

Optional: 

     PARAM NAME=BCOLOUR VALUE="Colour of background as hex number eg #FFFFFF"
          The colour of the applet behind the model. Use the same syntax as a webpage so white is #FFFFFF, black is #000000 and red would be #FF0000
     PARAM NAME=BIMAGE VALUE="URL, relative to document, of gif or jpg image to use as background." 
          A gif or jpg specified here will appear behind the model. Careful scaling and shifting of the model can give the illusion of a rendered background!
     PARAM NAME=LOADFRAMES VALUE="Number frames to load, then frame numbers IN ORDER, no spaces eg 4,0-3,5" 
          This is slightly fiddly but highly recommended. The default is to load all the frames and that is a lot of information and hence a lot of memory. I recommend
          loading as only as many frames as you need. You must have at least one frame! 
          Right. There are no spaces in this VALUE. The first number in this VALUE is the number of frames to load. Then there is a comma and the there is a
          list of the frames you want, in numerical order. Single values are separated by a comma, sets of consecutive frames are separated by a hyphen ('-'). The
          hyphened lists are inclusive so 5-8 will load frames 5,6,7 and 8. Remember the first frame is zero not one. Finally remember (and I admit I fell for this) if
          you ask for say 5-10 that is six frames (5,6,7,8,9 and 10) not five! 
          eg. "7,0-2,5,8-10" will load frames 0,1,2,5,8,9 and 10
     PARAM NAME=LOADSKINS VALUE= "Number skins to load, then skin numbers IN ORDER, no spaces eg 2,0,5" 
          Exactly the same as above. Again you must have at least one skin.
     PARAM NAME=YANGLE VALUE="An integer between 0-359" 
          Start with the model rotated this number of degrees about the vertical axis.
     PARAM NAME=XANGLE VALUE="An integer between 0-359" 
          Start with the model rotated this number of degrees about the left/right axis
     PARAM NAME=ZOOM  VALUE="A float (decimal number) representing the zoom level" 
          This number is best obtained from the monitor window in MDLView- press 'm'. Bigger number mean further away:- 'zoomed out'
     PARAM NAME=PALETTE VALUE="URL of Palette file, relative to codebase" 
          If you are annoying and don't want to put quake.pal in the CODEBASE directory then specify where you do put it. If you are cool (and annoying) and your
          skin uses a non-standard palette, here's where to tell MDLView.
     PARAM NAME=SHIFTY "Integer number by which to shift model vertically" 
          Some models have an origin which is not in the centre of the model- a good example is the quad damage model on the main page. This parameter shifts the
          model origin down by the specified amount. Best use trial and error to find a value. Be careful!
     PARAM NAME=FORMAT VALUE= "Name of the plugin format" 
          This feature is new in version 0.96. It allows third-party support for model formats. The name to use should be supplied or obvious. If it is not either
          then it will be the name of the java class for the format with out the 'MDL' prefix or the 'Model.class' suffix. 
          Eg. <PARAM NAME=FORMAT VALUE="rabbit"> will cause MDLrabbitModel.class to be used. This example presumably is for support of
          models in 'rabbit' format (and no, rabbit format is not a real format). 
          The default value is 'quake' (calling MDLquakeModel.class) which ensures backward compatability.

PARAM Values used by MDLMovie only:

Obligatory: 

     PARAM NAME=MOVIETYPE VALUE="Type of movie: 'ROTATE' or 'ANIMATE' " 
          MDLMovie can either produce movie where the model rotates or movies where it animates... here's your chance to choose. Remember if you are doing a
          rotate movie then you only want one frame of animation- more and at best MDLMovie will get annoyed. If you are doing an animate movie then remember
          you can currently only have up to 30 frames.

Optional: 

     PARAM NAME=DELAYTIME VALUE="Time between frames in milliseconds if > 100" 
          If (heaven forbid) you want to slow MDLMovie down (usually for rotate movies) then put in an integer here.

PARAM Values used by MDLView only:

Optional: 

     PARAM NAME=FCOLOUR VALUE="Colour of foreground as hex number eg #FFFFFF" 
          Exactly like BCOLOUR but for the colour of the wireframe mesh and the triangles in hidden-line mode. Not needed for MDLMovie since it is always in
          texturemapping mode.
     PARAM NAME=RENDERMODE VALUE="Start rendering mode- currently 'wireframe', 'hiddenline' or 'texturemapped' " 
          Do you want the model to start in wireframe, texturmapped or hidden-line? Go ahead and say so.
     PARAM NAME=ROTATE VALUE="Start with model rotating- either 'true' or 'false' " 
          If you want the model to start rotating about the vertical then set this to be true. The default is false.
     PARAM NAME=STARTSKIN VALUE="An integer representing the skin to start the model with" 
          Remember that this will be the number of the skin counted from amongst those loaded and that the first skin loaded is set to be skin zero- eg if
          LOADSKINS is 4,0,3-5, then skin 0 is 0; skin 3 is 2 and so on. If LOADSKINS is 2,5,11 then skin 5 is 0 and skin 10 is 1.
     PARAM NAME=CYCLE VALUE=" 'true or false'... start with model cycling through frames if true" 
          If set to true the model will start up cycling through the loaded frames as though 'c' had been pressed.

Tips and advice:

     Don't put too many applets on the same page- they slow the computer down and cause memory difficulties 
     Load as few skins and frames as you can- they are large data structures and applet memory is quite precious 
     Keep applets fairly small- scaling down an over-sized applet can work wonders. Try to use ZOOM to optimise the use of space. 

Technical details:

    For those who are interested, MDLViewCanvas is the class which actually performs the rendering. It can render only triangles and the texturemapping is not
    perpective correct. Hiddenline removal is achieved by sorting the triangles by their furthest points from the viewer. This method sometimes breaks down but is fast,
    simple and works 99% of the time. 
    Zipped models are supported by way of the standard 'ZipInputStream' class. This class is naturally required to view compressed models although you might be able
    to place the required classes in the same directory and have the browser download them- it depends on whether they use native methods- I haven't checked. 

Writing plugin format classes:

    If you are a java programmer with a love of 3D then step into the breach and add support for your favourate 3D format. Only models which obey, or can be made
    to obey, a set of rules can be rendered. If you are not a java programmer (or lazy) then I will try to add support for any format for which detailed specs can be
    offered and which seem likely to be used.  