//////////////////////////////////////////////////////////////////////////
        THIS FILE CONTAINS IMPORTANT INFORMATION AND INSTRUCTIONS
//////////////////////////////////////////////////////////////////////////

/*************************************************************************/
/*  The author makes no warranty of any kind, expressed or implied,      */
/*  with regard to the Data Compression Library, and to the accuracy     */
/*  of the specifications.                                               */
/*  The author shall not be liable for any loss or damages resulting     */
/*  from the use of any of the programs supplied.                        */
/*                                                                       */
/*************************************************************************/

///////////////////////////////////////////////////////////////////////////
 For a FASTER DECOMPRESSION library (approx. 15-20%) send 19.99 or $44.99
                           to the address below
///////////////////////////////////////////////////////////////////////////

The data compression libraries are specifically designed for the real time
decompression of graphical sprite type data. They may or may not be
suitable for other purposes.


----------------------------------------------------------------------------
                    Data Compression Library Files

The Shareware version of the Data Compression Libraries contains the 
following files. Feel free to distribute the Data Compression Libraries.

The following files are included in the DCLLIB archive :

DCL_386R.LIB      - Watcom C 386 Register based library
DCL_386S.LIB      - Watcom C 386 Stack based library
DCL_386.H         - Header file for Data Compression Library
EXAMPLE.C         - An example program for DCLLIB
EXAMPLE.EXE       - The example program, already compiled and linked
README.TXT        - This File
REGISTER.TXT      - If you want the faster libraries, or want to 
                    register so you can distribute your code then
                    you need to read this.


----------------------------------------------------------------------------

----------------------------------------------------------------------------
                        Using The Libraries

These Libraries are compiled specifically for WATCOM 386 C. There are no
other ports at this moment in time.
Use the library like any other, simply include the header in your program

#include "dcl_386.h"

And link one of the .LIB files into your code. There are two versions of the
library, one for register based parameter passing, and one for stack based
parameter passing.



/************************************************************************/
                 THE DATA COMPRESSION LIBRARY FUNCTIONS
/************************************************************************/

There are four functions which you will need to use, these are listed as ...

1. DCL_init_compress     - Initialises memory for library
2. DCL_close_compress    - Deinitialises memory for library
3. DCL_shrink            - Compress data
4. DCL_expand            - Expand data

Here is a more detailed look at the functions and how they work.

------------------------------------------------------------------------
FUNCTION : Initialise Compression Library
int DCL_init_compress(unsigned int uncomp_buf, unsigned int comp_buf);

RETURNS:
0    - if unsuccessfull (not enough memory).
1    - if successfull

EXAMPLE:
error=DCL_init_compress(20000,20000);

if(error==NULL) {
    printf(Cannot alocate memory !\n");
    exit(1);
}

This example simply allocates 20k for both compression and decompression.
ie. the size of the compressed and uncompressed sprite frame must not
exceed 20,000 bytes. 

NOTES:
All this function does is allocates two blocks of memory, one is the
uncompressed buffer (uncomp_buf), and the other is the compressed buffer
(comp_buf). The arguments both represent number of bytes to allocate.

The decompression uses the memory in uncomp_buf to decompress to (see
the relevant function, it will return a pointer to this location), and
the compression routine will compress to the comp_buf.

These two buffers are simply located in global memory and are used to
reduce the chance of memory fragmentation. You could set these arguments
just before compressing, and decompressing, if you knew the exact sizes
of both. However, if you don't know exactly how big these need to be
then just make them as big as you will need.

For example, if all your sprites to be compressed are under 15k per frame
then make both buffers 15k big. It might be a good plan to add on a bit for
safety.

You only need to call this function once at the start of your program.

You can bypass this function manually. There is little reason why you would
want to but, just incase, this is how to do it.
There are two variables which are pointers to unsigned char. These are

unsigned char *DCL_tbuffer;
unsigned char *DCL_dest;

These are globals, if you wish to use them just define them as external.
The first is a pointer to the uncomp_buf, the second is a pointer to the
comp_buf. You may allocate and reference these directly if you so wish.

------------------------------------------------------------------------
FUNCTION : Uninitialise compression library
void DCL_close_compress(void);

RETURNS:
nothing.

EXAMPLE:
DCL_close_compress();

NOTES:
This function should be called when you are finished either compressing
or decompressing. All it does is free DCL_tbuffer and DCL_dest. Once again
you could do this manually if you wish.

------------------------------------------------------------------------
FUNCTION : Compress some memory data
unsigned char *DCL_shrink(unsigned char *source,unsigned int *length);

ARGUMENTS:
source - A pointer to the start of the data you wish to compress.
length - The number of bytes you wish to compress.

RETURNS:
Pointer to compressed data (ie. globally allocated DCL_dest).
Also returns the size of the uncompressed data in 'length'

EXAMPLE:
compressed_data=DCL_shrink(source,&length);

NOTES:
This function takes the data from the pointer 'source' and places it into
the globally allocated destination (created when you did DCL_init_compress).
It always returns a pointer to DCL_dest because that is where data is always
compressed to.

------------------------------------------------------------------------
FUNCTION : Uncompress some memory data
unsigned char *DCL_expand(unsigned char *source,unsigned int *length);

ARGUMENTS:
source - A pointer to the start of the data you wish to uncompress.
length - used for return only (see below).

RETURNS:
Pointer to the uncompressed data (ie. globally allocated DCL_tbuffer).
Also returns the size of the uncompressed data in 'length'

EXAMPLE:
compressed_data=DCL_expand(source,&length);

NOTES:
This function takes the data from the pointer 'source' and places it into
the globally allocated destination (created when you did DCL_init_compress).
It always returns a pointer to DCL_tbuffer because that is where data is 
always uncompressed to.

-----------------------------------------------------------------------

GENERAL COMMENTS:

If things are still unclear then you should have a look at the example file
'example.c'.

There isn't much error checking here (apart from the memory allocation).
It really is up to you to know what you are doing. This library is
pretty simple, so not much is needed anyway.

The most likely way for the program to crash is if you dont allocate enough
memory in DCL_init_compress. Because this library was designed specifically
for sprites, it just allocates this Global memory once, then re-uses it for
all compression and decompression. Remember that as they are single instances
of global buffers, you will need to move or use the data BEFORE you try to
'expand' or 'shrink' again.

In the case of a sprite system, you would make this function 'invisible' by
placing it inside your draw sprite routine, so just before drawing the sprite
to screen or a buffer, you decompress it.

If the libraries seem a bit limited then sorry. They were written for for a
specific use and it is possible that there are uses for which they are not
particularly well suited. Once again, sorry, but I don't have time to write
everything.

I will try to release more stuff in the future, but that really depends on
how much support I get from you people. If you register and get the faster
libraries then that will also be an incentive to myself. I'm thinking of
an animation player next (lossy), because, apart from very expensive 
commercial systems, there doesn't seem to be much about. Well, 
thats another day ...


Correspondence to :

            Dani Arrusi
            6 Swan Road
            West Drayton
            Middlesex UB7 7JY
            England

E-mail : dani@minor.demon.co.uk
