quakemdl (v1) By Preach

This is a perl module of dubious quality which attempts to provide an easy way to modify quake models in a "mechanical" way. The zip contains two folders:

quakemdl
What to do with it: copy the folder to your perl 'lib' folder. This installs the module, please don't imagine something this rough round the edges is going on CPAN.

examples
What to do with it: Look through the pair example .pl scripts and maybe try running them on some models.


	Guide for writing scripts:

To import the module add
use quakemdl::mdl;
to the top of your script.

The useful functions available to you are

 mdl::read_model
  Takes a single parameter of the filehandle to read a model from.
  Returns a reference to a perl structure which corresponds to the model.

 mdl::write_model
  Takes two parameters: a reference to a perl structure describing the model to 
  save, followed by the filehandle to write it to.

 mdl::get_pixel_for_vertex
  Takes a handle to the model structure, then the index of a vertex in that model,   then the index of the skin required. Returns the value of the colour of the skin   under that vertex on the model.

 mdl::list_framedata
  The structure representing the model in this script allows the collection of
  frames to contain both single frames and groups of frames collected to animate
  client-side. Sometimes you just want to modify the data within each frame without
  needing to consider whether the frame belongs to a group or not. Pass this   function a reference to the model structure and it will return an array of
  references, one for each set of framedata.

Please read the comments at the bottom of quakemdl/mdl.pl for a picture of how the quake model format has been represented in the structure returned by read_model.

Also work through how the examples work. example.pl just performs a few daft tasks like deleting all but 1 skins from the model just to demonstrate how the model structure can be manipulated. fixnorms.pl is more in depth and is actually useful! It takes a model as you might create with a complex skin map, and tidies up the vertex normals so that the seams don't show up.

WARNING I: Although the loading functions are fairly good at screening for a bad input file (eg a corrupt .mdl file or something that's not in .mdl format), the saving functions basically assume you've preserved the structure given to you. As an example of what can go wrong, consider a vertex entry in a frame. These are provided in arrays of length 4 for the x, y, z and normal entries. If you tag an extra element onto the array, the write_model function will happily write the extra byte to the model and silently corrupt the rest of the model.

WARNING II: Because I am fairly new to perl, I may discover that the interface I've designed here is inefficient or inept. I reserve the right to release the next version and make it in no way compatible with the current one. This is a first attempt and so not stable...

	The future:

Future goals include:

* Adding some code for handling the mysterious vertex normals - including the vertex normal table and finding the index that best approximates a given normal.

* Creating a companion to mdl::list_framedata which provides a list of skindata which ignores whether a skin is in a group or not.

* Including more example scripts.

* Creating a companion module which will load MD3 (then maybe MD2) models into a similar perl structure. Then include example scripts for loading an MD3 and outputting a MDL.

The last one ought to be useful in practice. I was at one point working on a new version of md3tomdl with expanded options for how the conversion would be performed. I abandoned this when the challenge became parsing the config file rather than performing the conversion. Instead I began looking for a scripting language which handled binary files and there perl was...