JCALG1 r5.xx
(c)1999-2001 Jeremy Collake
http://www.CollakeSoftware.com
support@collakesoftware.com

This software is provided as-is, without warranty of ANY KIND, either expressed or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose. The author shall NOT be held liable for ANY damage to you, your computer, or to anyone or anything else, that may result from its use, or misuse. Basically, you use it at YOUR OWN RISK.

License
This library may be used freely in any and for any application.

Credits
First of all, I would like to credit Joergen Ibsen, author of apLib, for many suggestions and help with my development of JCALG1. You may notice some similarities between the JCALG1 decompressor and that of apLib. The reason for this is because I could not come up with a better encoding scheme than Joergen Ibsen's. Therefore, I give him credit to developing much of the encoding scheme that JCALG1 uses.

Synopsis
JCALG1 is a small, open-source, LZSS derived compression library.

Features

Coded in 100% 32bit x86 assembly language for maximum performance and minimum size.
Good compression ratio, typically much better than ZIP's deflate.
Extremely small and fast decompressor.
Adjustable window size to allow for faster compression at the cost of compression ratio.
Decompression requires no memory, other than the destination buffer.
Easy integration with any application.
Free!

Canterbury Corpus compression results for JCALG1 with window size of 128Kb (c7)::

File	Original Size	Compressed Size	Bits Per Byte	Weighted
bib	111,261	36594	2.63
book1	768,771	335310	3.49
book2	610,856	213402	2.79
geo	102,400	71022	5.55
news	377,109	142978	3.03
obj1	21,504	9982	3.71
obj2	246,814	77722	2.52
paper1	53,161	20014	3.01
paper2	82,199	32534	3.17
pic	513,216	58338	0.91
progc	39,611	14194	2.87
progl	71,646	17174	1.92
progp	49,379	11674	1.89
trans	93,695	19486	1.66
TOTAL:	3,141,622	1060424	2.80	2.70

Documentation

This is where I tell you what you need to know, ever-so-briefly ;). I decided to document all functions in C, since most people are familar with it. All functions use the STDCALL calling convention (parameters pushed onto stack, called function adjusts stack before return).

DWORD JCALG1_Compress(: void *Source,; DWORD Length,; void *Destination,; DWORD WindowSize,; AllocFunc *pAlloc,; DeAllocFunc *pDealloc,; CallbackFunc *pCallback,; BOOLEAN bDisableChecksum);

Parameters

Source is a pointer to the uncompressed data.
Length is the size of the uncompressed data.
Destination is a pointer to the destination of the compressed data. This buffer should be at least 4 bytes larger than the uncompressed data size. One can retrieve the minimum needed buffer size by issuing a call to JCALG1_GetNeededBufferSize.
WindowSize is a nonzero value up to the size of the file. The larger, the better the compression ratio but the slower the compression.
pAlloc is a pointer to a memory allocation function. See prototype below.
pDealloc is a pointer to a memory deallocation function. See prototype below.
pCallback is a pointer to a callback function which is called in every iteration of the main compression loop. See protoype below.
bDisableChecksum, if TRUE a checksum for the data is not computed/stored.

Returns: Size of the compressed data, or NULL if the data could not be compressed.

DWORD JCALG1_Decompress_Fast(: void *Source,; void *Destination);
DWORD JCALG1_Decompress_Small(: void *Source,; void *Destination);

Parameters

Source is a pointer to the source data.
Destination is a pointer to the destination buffer for the uncompressed data.

Returns: Size of the uncompressed data or 0 if the block of data is not a valid JCALG1 compressed stream (failed header or checksum tests). As the function names attempt to infer, the 'small' version of this procedure is the one optimized for size while the 'fast' version is the one optimized for speed.

DWORD JCALG1_GetUncompressedSizeOfCompressedBlock(: void *pBlock)

Parameters

pBlock is a pointer to a JCALG1 compressed block of memory.

Returns: Size of the uncompressed block, in bytes.

DWORD JCALG1_GetNeededBufferSize(: DWORD n Size);

Parameters

n Size is size, in bytes, of a block of uncompressed data.

Returns: The minimum destination buffer size (currently nSize+4).

void JCALG1_GetInfo(: _JCALG1_Info *JCALG1_Info);

Parameters

JCALG1_Info is a pointer to a _JCALG1_Info structure.

typedef struct __JCALG1_Info {: DWORD MajorRev;; DWORD MinorRev;; DWORD FastDecompressorSize;; DWORD SmallDecompressorSize;
} _JCALG1_Info;

BOOL CallbackFunc(: DWORD pCurrentSrc,; DWORD pCurrentDest);

Parameters

pCurrentSrc is the relative offset of the current position in the uncompressed data.
pCurrentDest is the relative offset of the current position in the compressed data.

Return: FALSE to stop compression, TRUE to continue compression.

void *AllocFunc(: DWORD Size);

Parameters

Size is the number of bytes requested.

Returns: Pointer to allocated memory block.

BOOL DeallocFunc(: void *pMemory)

Parameters

pMemory is a pointer to the memory block to be deallocated.

Returns: FALSE if failure.