Description
-----------
This is a library that provides functions to interpret and write
Descent 3 demo files. It is written in C to allow for fast
processing of demos, but also provides bindings to the Lua
scripting language to make it easier to inspect demos and to
perform various simple operations on them without having to go
through the hassle of coding up a new C program. This even makes
it possible to inspect and edit demos interactively to a certain
extent.

I've designed the interface to be small and simple, and I've
taken care to avoid memory hogs. This naturally comes at the cost
of some flexibility: demos can be read and written sequentially
only; other than rewinding to the start, you can't move around in
a demo. Furthermore, the reader and writer are separated; the
only way to change a demo is to write a new modified version and
then replace the original demo by it.

 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Note: before you decide to use this library in your programs,     *
 * make sure you understand its licensing terms. See the additional  *
 * licensing info section of this README file.                       *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Credits
-------
The work on reverse engineering the D3 demo file format was not
done by me, but the person who did it did not wish to receive
credit for it.

Portability
-----------
This library has been developed on a GNU/Linux system, and so far
has not been tested on any other platform. Here's a list of known
portability issues that may arise:

* It relies on packing of structs. The method used to achieve this
  is not standardized and differs between compilers. Currently,
  only the GNU compiler is supported. Fortunately it's available
  for almost any platform.

* It relies on the platform being little-endian, since it reads
  demo data directly into structs. This shouldn't be a problem as
  Descent 3 itself was designed for a little-endian platform
  anyway.

Installation
------------
See the file INSTALL for installation notes.

API documentation
-----------------
The header files, together with the example code (which can
be found in the "examples" directory), should provide you with
all the information needed to know how to use the library. An
explanation of the Lua API can be found in the README file
in the "lua" directory, and example Lua code can be found in
the "lua/examples" directory.

Author / copyright / warranty
-----------------------------
Copyright (C) 2008  Pim Goossens

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this library; if not, see <http://www.gnu.org/licenses/>, or write
to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA.

Additional licensing info / clarification
-----------------------------------------
This library is licensed under the GNU GPL, *not* the GNU LGPL.
This means that any program that uses this library can only be
released under the GNU GPL, since it effectively constitutes a
part of the program and no exception is made for linking to this
library.

This includes Lua scripts that use the d3demo module, but for
convenience reasons I don't require you to include a full copy
of the GPL with such scripts; just make sure its users know where
to get it and the full d3demo library source code, and don't add
any further legal restrictions.

I made this choice because I want to make sure that all programs
that use this library give their users the same freedom that
comes with this library: permission for anyone who wishes to do
so to use, modify, and/or redistribute them. The GNU GPL is the
tool used to ensure this.

Contact information
-------------------
Email: lion@descentforum.net
