JCALG1 – Compression Library
NOTICE: This is a legacy project originating 20 years ago.
JCALG1 is a lossless compression algorithm loosely based on LZSS. It is written entirely in x86 assembly. It compresses very well, though is slow to compress. Decompression is as rapid as any other LZ77 derivative. It has a unique ability to handle pre-compressed or high entropy data.
JCALG1 r5.xx
(c)1999 Jeremy Collake
http://www.bitsum.com
Download: Library and x86 assembly source
License: MIT
Credits: Joergen Ibsen, author of apLib, was instrumental during this algorithm’s development. Much of the encoding is similar to that of apLib.
Synopsis: JCALG1 is a small, open-source, LZSS derived compression library.
Features:
- Written in 100% 32-bit x86 assembly language for reasons that made sense at the time.
- 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 additional memory (other than output 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
All functions use the STDCALL calling convention (parameters pushed onto stack, called function adjusts stack pointer 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.