Hufflib Library

Filename

Hufflib Library

Summary

Huffman decompression library

Authors

Jimmy Mardell

Ticalc.org URL

Original TI-92 version 1.1

Release Date

May 19, 1997 (original version)

Compatibility

TI-83/83+/84+/85/86/89/92

Language

Assembly

Hufflib Library is a Huffman decompression library written by Jimmy Mardell. It was originally coded for the TI-92 calculator, and then later ported to many of the other TI calculators for use in various games.

Significance

The library has been used in various games across many of the TI calculator range. Notable uses include Sqrxz by Jimmy Mardell (first on the TI-85/86 calculators, then later ported to the TI-83/83+/84+ series), as well as many of the Alien Breed games by James Vernon (across the TI-83/83+/84+ series).

Documentation

Data is compressed on PC using the HUFFMAN.EXE program, and then this compressed data is incorporated into calculator program. During program execution, the appropriate routine is called to extract the compressed data. The exact method and memory requirements vary slightly between the Z80 calculators and the 68K calculators, however the concept is the same.

A portion of the original TI-92 readme file is included here:

HOW TO COMPRESS


When using the compression program, all parameters except the last one
are input files, and the last parameter is the output file.

Lets say you have a picture stored as binary file, 3840 bytes, and the
name of the file is 'coolpic.bin'. To compress it, you would type

C:\FARGO\>huffman coolpic.bin coolpic.huf

When compressing, some information is shown, and at the end, the ratio
which may be of interest:

3840 bytes -> 1735 bytes (ratio 54.82%)

The picture has decrease 54.82% in size!

You can also compress many files into one archive. You should do that
when compressing similiar things, for example if you have a lot of small
levels in a game. Since levels often have similiar patterns, the compression
usually gets better if you have one big archive instead of lots of small.

If you want to compress a picture and lots of levels, it may be better
to make two archives, one with the picture compressed and one with
all levels compressed. But you should still check the size if you make
only one archive of it because it might be better.

To compress many files into one archive, type something like

C:\FARGO\>huffman level1.bin level2.bin level3.bin level4.bin levels.huf

If an input file is a text file instead of a binary file, you must add
the switch -t before the file name (the output file will always be a binary
file). For example, if you want to compress the textfiles 'text1.txt',
'text2.txt' and the binary file 'levels.bin' into one archive, 'misc.huf',
you should type like this:

C:\FARGO\>huffman -ttext1.txt -ttext2.txt levels.bin misc.huf

The textfiles should only contains DC.B, DC.W or DC.L with data in the
same format as A68K uses. See below for more details.

If you want to store many files in an archive, you could make a listfile.
If you put the switch -l in front of a filename, it means that the files
listed in that listfile will substitute the listfile. For example, assume
'file.lst' looks like this:

-tfile3.txt
file4.bin
files.huf

and you type

C:\FARGO\>huffman file1.bin -tfile2.txt -lfile.lst

the files 'file1.bin', 'file2.txt', 'file3.txt' and 'file4.bin' will
be archived into 'files.huf'. The list file can be anywhere in the
parameter list, and you can have many listfiles. You can't, however,
have a listfile in a listfile (ie, a file with -l in front of it in
a listfile will not act as a listfile, but a binary file starting with
-l). The output file may be in the listfile, as in the example.

HOW TO EXTRACT


You can't extract a compressed archive with HUFFMAN.EXE (at least not in
this version, may be added later), you must extract within a Fargo program
using hufflib. There are four different functions for extrating: extract,
extract_string, write_string and write_string_inv. There is also a memory
checking routine, check_mem.

FUNCTION: extract


A0 should point to the huffman compressed data, and A1 to where you want
to store the extracted data. When calling hufflib[extract], you must have
1024 bytes free memory, else nothing will happen.

When extracting from a multifile archive, you must choose which file
to extract. You load D3.W with the file number (the first file has
number 0) and then call hufflib[extract]. D3 MUST be in range 0<=D3<noFiles;
there is no check for this. When extracting from an archive which only
contains one compressed file, D3.W can be any value - it will be discarded.

Development History

  • May 1997 — Original TI-92 version released
  • August 1997 — Original TI-85 version of Sqrxz released, which incorporated Hufflib
  • July 1998 — TI-83 port of Sqrxz released
  • October 1999 — Alien Breed II v1.2 released on the TI-83 (the first version that incorporated Hufflib)

Related Products