
 MM          MM  DDDDDDDDDDDD    LL
 MMMM      MMMM  DD          DD  LL                    II        BBBBBBBBBB
 MM  MM  MM  MM  DD          DD  LL                    II        BB        BB
 MM    MM    MM  DD          DD  LL                    II        BBBBBBBBBB
 MM          MM  DD          DD  LL                    II        BB        BB
 MM          MM  DD          DD  LL                    II        BB        BB
 MM          MM  DDDDDDDDDDDD    LLLLLLLLLLLLLL        II        BBBBBBBBBB
                                                     

            A 3D model programming library     Version 0.45  Beta

                  By Pedro Ramalhete 1999



#include <std_disclaimer.h>

   "I do not accept responsibility for any effects, adverse or otherwise, 
    that this code may have on you, your computer, your sanity, your dog, 
    and anything else that you can think of. Use it at your own risk.
    Quake 1 and Quake 2 are trademarks of Id Software and 3D Studio is
    trademark of Autodesk. I am in no way involved with any of this companys."


======================================
============ Introduction ============
======================================

   MDLib is a library of functions for 3D fans and specially Quake fans. It's
   fully written in C and uses Allegro 3.11 with the DJGPP compiler, so you
   need to have them both installed in your computer if you're planning on
   doing anything with MDLib.
   The official page is the Clan 7 homepage at
   http://go.to/Clan7
   but send questions & bugs to l41273@alfa.ist.utl.pt


==================================
============ Features ============
==================================

   Rotate, zoom, animate and move Quake 1, Quake 2 and ASCII models.


===================================
============ Copyright ============
===================================

   MDLib is gift-ware and is given to you freely as a gift. You may use,
   modify, redistribute, and generally hack it about in any way you like,
   and you do not have to give us anything in return. However, if you like
   this product you are encouraged to thank us by making a return gift to
   the Allegro community. This could be by writing an add-on package,
   providing a useful bug report, making an improvement to the library
   (Allegro or MDLib), or perhaps just releasing the sources of your program
   so that other people can learn from them. If you redistribute parts of
   this code or make a game using it, it would be nice if you mentioned
   Allegro and MDLib somewhere in the credits, but you are not required to
   do this. We trust you not to abuse our generosity.




============================================
============ Installing MDLib ==============
============================================

   - Go to wherever you want to put your copy of MDLib (your main djgpp
     directory would be fine, but you can put it somewhere else if you 
     prefer), and unzip everything. MDLib contains several subdirectories,
     so you must specify the -d flag to pkunzip.

   - Type "cd mdlib", followed by "cd src" and then "make". If all goes
     according to plan you will end up with libmdl.a and mdlib.exe which
     is an application to browse PAK files.

   - You can now compile an example (the only one for now):

      gcc ex1.c -o ex1.exe -lmdl -lalleg


=======================================
============ Using MDLib ==============
=======================================

All the MDLib functions, variables, and data structures are defined in
mdlib.h. You should include this in your programs, and link with
libmdl.a. To do this you should:

   - Put the following line at the beginning of all C or C++ files that use 
     MDLib:

         #include <mdlib.h>

   - If you compile from the command line or with a makefile, add
     '-lmdl -lalleg' to the end of the gcc command (the order IS important!):

         gcc foo.c -o foo.exe -lmdl -lalleg

   - If you are using Rhide, go to the Options/Libraries menu, type 'mdl'
     into the first empty space and 'alleg' in the next one, and make sure
     the box next to them are checked.



========================================
============= 3D Routines ==============
========================================

int MDLCheckType(char *filename);
   Returns the type of 3D model. If you want you can read the file from a
   DATAFILE like this:

      MDLCheckType("mydata.dat#model1");

   This function uses the 4 first bytes of the file to identify it, so the
   file extension has no effect.
   Possible return values are:

TYPE_MDLQ1:
   Quake 1 .mdl file. To display it properly you must use the Q1 palette
TYPE_MDLQ2:
   Quake 2 .md2 file. To display it properly you must use the Q2 palette
TYPE_MDLQ3:
   Quake 3 .md3 file. Not supported yet, besides, the game itself will
   probably use .md4, so .md3 won't be of much use.
TYPE_MDLHL:
   Half-Life .mdl file. Can't display yet because it needs 16 bit color modes
   and very complicated skeleton/animation stuff  :(
TYPE_ASC:
   ASCII file format (for mesh only) used by Q2Modeler and a few more 3D
   programs.
TYPE_3DS:
   3D Studio format. Not supported yet.
TYPE_UNKNOWN:
   File damaged or unrecognized.


mdl_t MDLLoad( char *filename );
   Load a model file. For now it can be only be a Q1, Q2 or ASCII model.
   Returns a struct of type model with a non null pointer to the type of
   model that is or sets the type to TYPE_UNKNOWN.


void MDLUnload( mdl_t *model );
   Free memory that is no longer in use by the model.


void MDLUpdateView( camera_t cam, mdl_t *model );
   Rotate and move the points of the model according to a camera.


void MDLDrawPoints( BITMAP *dbuf, mdl_t *model );
   Draw a bunch of points which are the vertex coordinates of the model.


void MDLDrawWireframe( BITMAP *dbuf, mdl_t *model );
   Draw the model with wireframe triangles.


void MDLDrawFlatShade( BITMAP *dbuf, mdl_t *model );
   Draw the model with flat shaded triangles. Each triangle has a color
   according to it's orientation.


void MDLDrawTexture( BITMAP *dbuf, mdl_t *model );
   Draw the model with POLYTYPE_ATEX textures. I know it would be better
   to use POLYTYPE_PTEX, but it would also be slower, in the future I might
   create another function to draw with perpective corrected textures.
   Please remember that ASCII models do not support textures, so if you try
   to draw one with this function, you will see absolutely nothing!


void MDLDebug( mdl_t *model );
   Show info on the model. Very usefull for finding out if a particular file
   is damaged or why isn't it supported.



========================================
============= Unpak Routines ===========
========================================

pakentry_t *PAKLoadDir( char *pakfilename, long *num_files );
   Loads the directory information of a .PAK file and stores the number of
   files in num_files, returning the list of entrys (files) in the PAK.


long PAKExtractFile( char *pakfilename, pakentry_t entry );
   Extract a file (entry) from the PAK pakfilename to the current directory.
   eg:

   pakentry_t *filelist;
   int numfiles;

   filelist = PAKLoadDir("c:/quake2/baseq2/pak0.pak", &numfiles);
   PAKExtractFile("c:/quake2/baseq2/pak0.pak", paklist[ 0 ]); // extract the first file




========================================
============= PAKs & MDLs ==============
========================================

   So you don't have Quake 1 or Quake 2 so you don't know where to get models?
   What are you waiting for? Go out to the nearest computer store and buy
   those great games!
   What? Still not enough? You want MORE models? Then take a look at:
   http://www.planetquake.com

   Choose a mod, download it and see if any of the models in the PAK interest
   you, but remember that you can't use other peoples models in your
   demo/games without asking for their permission first!

   DO NOT ask me for Q1, Q2 or 3DStudio models or the applications, you will
   get no response! DO NOT ask me for the source code of Q1 or Q2 because I
   don't have them, all my code was based on the Quake specs and the rest I
   found out myself debuging the model files.









Coded by Frodo The Ring Bearer                           Clan 7 RuleZ !!!
