
                           LZA Utilities, Package 3
                           ------------------------

Index
-----

     Disclaimer and Warranty
  1. Introduction
  2. System Requirements
  3. Using and Copying the LZA Utilities
  4. Guide to LZA Desktop
     4.1. Loading/Opening Animation Files
     4.2. Loading/Opening PCX Sequences
     4.3. Saving LZA files
     4.4. Playing animations
     4.5. Changing Replay Speed
     4.6. Setting the Options
  5. LZA Desktop, Troubleshooting
  6. Compiling the Source Code
  7. LZA Technical Specifications
     7.1. File format for LZA
     7.2. Implementation notes
     7.3. Performance of LZA
     7.4. LZO Note


Disclaimer and Warranty
-----------------------

This product is distributed AS IS. The author specifically disclaims all
warranties, expressed or implied, including, but not limited to, implied
warranties of merchantability and fitness for a particular purpose with
respect to defects in the diskette and documentation, and program license
granted herein, in particular, and without limiting operation of the program
license with respect to any particular application use or purpose. In no event
shall the author be liable for any loss of profit or any other commercial
damage including but not limited to special, incidental, consequential or
other damages.


1. Introduction
---------------

LZA files are compressed animation files. The LZA format was invented by
Brian Strack Jensen, aka. goto64 of Purple, and can be used freely. In this
package you find 3 utilities. Two of them are command line utilities: 

FLI2LZA.EXE: This program can convert Flic (.FLI and .FLC) files to LZA files.
PLAYLZA.EXE: This program can play a LZA file.

Also included is a desktop utility (LZA_DESK.EXE). This desktop utility has a
pleasant and user frindly graphic interface. It can play both Flic, LZA and
PCX sequence animations and save flic and PCX sequences as LZA files.

The package also includes the Watcom C source code for the animation player.
You can use this in your own programs, free of charge (it would of course be
nice if you credit me).


2. System Requirements
----------------------

FLI2LZA:     386+, 2Mb RAM.
PLAYLZA:     386+, 2Mb RAM, VESA 2.0 compatible driver and graphics card for
             resolutions above 320x200.
LZA Desktop: 386+, 4Mb RAM, VESA 1.0 compatible driver and graphics card,
             a Microsoft compatible mouse. 


3. Using and Copying the LZA Utilities 
--------------------------------------

All of the LZA utilities are freeware. This means that you can use them free
of charge for as long as you like. However, if you like these utilities, a
small contribution of cash, a postcard or just a friendly e-mail would be
appreciated. In particular if you are a programmer yourself and are using
the LZA format in one of your programs, I would be interested in hearing from
you. We would also appreciate if you report any bugs that you find.

Contacting info:

  E-mail:                  purple@diku.dk or stencil@image.dk
  Snail Mail:              Brian Jensen
                           Lindevej 2
                           Jorlunde
                           DK-3550 Slangerup
                           Denmark

  WWW homepage for Purple: http://www.diku.dk/students/purple/

  Also check out Stencil's Purple related homepage with the Contrast on-line
  magazine: http://www.image.dk/~stencil/


4. Guide to LZA Desktop
-----------------------

LZA Desktop uses a graphical interface, with pull-down menus and dialog boxes,
much like the interface of Windows and many graphical DOS applications. If
you already know how to work with such interfaces, you can skip to section 4.1.

To activate a pull-down menu you can either click on its header in the menu
bar, or while holding down the ALT key, press the underlined letter.
Each menu has two or more items. Move the colored bar across the items, using
the mouse or the up/down cursor keys. Click the left mouse button or press
enter when the bar is on top of the item you wish to select.

Often your choice in the menu will bring up a dialog box. In the dialog boxes
you can either use the mouse to click on the various elements, or you can
move between them by pressing the TAB key.


4.1. Loading/Opening Animation Files
------------------------------------

LZA Desktop supports two animation file formats: LZA and Flic. To Load/Open
a LZA file, select "Load LZA file" or "Open LZA file" from the "File" menu.
To Load/Open a Flic file, select "Load FLI/FLC file" or "Open FLI/FLC file"
from the "File" menu.

The difference between loading and opening is:
 - When loading a file, all frames will be decompressed and stored in memory
   as raw image data. The advantage of opening is that the replay speed will
   usually be fast. The disadvantage is that it requires a lot of memory.
 - If you do not have sufficient memory available, you can open the file
   instead. When a file is opened, frames will be read from the disk and
   decompressed to memory when needed. Only one frame is in memory at a time.
   The advantage is that you need much less memory. The disadvantage is that
   while playing the animation, time consuming disk access and decompression
   is needed for every frame.

When you chose to load/open a LZA or Flic file, dialog box appears. The box
contains a directory listing, an inputline and two buttons. The directory
listing will show only those files that have the extension .LZA (if you are
in the LZA dialog) or .FLI/.FLC (if you are in the Flic dialog). You can
access the listbox by clicking on one of the lines, or by pressing TAB twice.
In the box, you can move the light bar by using the cursor keys and page up/
page down. You can also scroll the listing by dragging the scrollbar on the
right side. Press enter or doubleclick on a filename/dirname to select it.
You can move back one directory by clicking on "..". When you find the file
you want, position the light bar on top of it. Now press the enter key, or the
"Ok" button or doubleclick on it, to select it. If the file ends on something
else than .LZA/.FLI/.FLC and is therefore not displayed in the file listing,
you can go to the directory which contains the file, and then jump to the
text inputline by clicking on it, or pressing TAB a number of times. Here
you can write the filename, and then press enter or click on the "Ok" button.

NOTE: Only 256 colour animations are supported.


4.2. Loading/Opening PCX Sequences
----------------------------------

(See 4.1 for difference between loading and opening).
Instead of using a real animation file, you can put together an animation,
using a number of images. LZA Desktop can only read images that are stored
in the PCX format. This format is supported by many graphics programs such as
Deluxe Paint, Photo Shop, Paint Shop and Paintbrush.

Select "Load PCX sequence" or "Open PCX sequence" from the "File" menu. Now
a dialog box appears. The file listing on the left works the same way as in
the LZA/Flic dialog (see 4.1), but this time only files with the extension
.PCX are displayed. To the right is another file listbox. This one shows the
files which you have selected for your animation sequence. Initially it is
empty. In the file listbox doubleclick or press enter on a filename to select
it for your animation. You can also position the lightbar on it, and then
click on the "Add ->" button. This way you can add files to the end of your
animation. If you want to insert a file somewhere else in the sequence, select
a file in the animation sequence listbox, and use the "Ins ->" button to
insert files directly above the selected file. If you accidentally add a file
which you do not want in your animation, you can select it in the listbox and
then click on the "Remove" button. If you wish to remove all files from the
animation sequence listbox, click on the "Clear" button.

When you have your animation sequence ready, click on the "Ok" button.
If you enter the dialog box again, the animation sequence will still be
displayed in the listbox so you can always go back and make changes to the
sequence.

NOTE: All the files must be of the same dimensions.
      Only 256 colour images are supported.


4.3. Saving LZA files
---------------------

Whichever file type you have loaded/opened you can always save it as a LZA
file. This means that you can convert Flics and PCX sequences to LZA files.
Select "Save as ..." from the "File" menu to save the currently loaded/opened
animation file. As usual, a dialog box shows up. It works much as the Load/
Open dialogs. You can select a save file name in the file listbox (this file
will of course be overwritten), or you can type in a name on the inputline.

The dialog also contains an inputline where you can set the skip percentage.
Initially it is set to 80%. You can type in another value (between 0 and 100),
or you can click on the up-down arrows in the right side of the inputline.

The skip percentage setting determines when the compression routine will
choose to use the skip compression instead of the LZO compression. The skip
percentage is the number of pixels on a horizontal line which has to be the
same as those on the previous frame, before skip compression is selected.
80% is a good compromise, but often you can lower the LZA file size up to 10%
by adjusting the skip percentage setting. If you want the details of these two
different compression methods, read part 7. Basically, you should try setting
a low skip percentage if a lot happens in a thin vertical bar of each frame,
while very little changes in the surroundings.

Here is an illustration of this situation:
line 1    -----+++-- 70%
line 2    --+++++++- 30%           
line 3    -----+++-- 70%         (+ marks changing area, - the unchanging)
line 4    ------++-- 80% 
line 5    ------++-- 80%
line 6    ------++-- 80%

In this case, 70% seems like a good choice for the skip percentage. In this
case there is a good chance you can lower the file size by using 70% instead
of 80%.

NOTE: If you have opened a file, you cannot save it to the same filename. When
      saving an opened file, since it will start overwriting the opened file,
      before all the data needed from it, has been loaded.


4.4. Playing animations
-----------------------

Once you have opened/loaded an animation, you can play it by pressing the
space key or by clicking the play button on the toolbar in the lower right
corner. Alternatively you can step one frame back or forth by pressing the
left/right cursor keys, or clicking on the << and >> toolbar buttons. By
pressing the home and end keys you can jump to the first and the last frame
of the animation.


4.5. Changing Replay Speed
--------------------------

You can change the replay speed of an animation. Select "Frame delay" from
the "Options" menu. In the dialog you can change the delay between each
frame, using the up/down buttons on the right side of the inputline. Alter-
natively you can click on the inputline and write a new value.


4.6. Setting the Options
------------------------

Select "Interface options" from the "Options" menu. Now the options dialog
appears. You can change two things:

Firstly, the way the next/previous buttons on the toolbar works. There are
three different settings. The first one is to use the normal animation delay.
This means that when you hold down the mouse button on the next or previous
button, it will change frame repeatedly, playing the animation at the same
speed (if possible) as when you play the animation. The second possibility
is one mouse click per frame. With this option you have to click and release
the mouse button every time you wish to change frame. The last possibility
is to have no delay. This way the animation will be played as fast as
possible when you hold down the mouse button on one of next/previous buttons.

Secondly, you can set the brightness of the graphics. Initially brightness is
set to 50. If you increase it, the graphics will become brighter. However, you
will not see the difference before you exit the dialog.

Note that the options are saved in a configuration file, and will be reloaded
every time you start the program.


5. LZA Desktop, Troubleshooting
-------------------------------

PROBLEM:  When I try to start the program, it just says "VESA mode 640x480x256
          not available".
SOLUTION: This probably happens because you do not have a VESA driver
          installed. If no VESA driver is supplied with your card, try using
          SciTech's UNIVBE driver (shareware version available on
          ftp.scitechsoft.com).

PROBLEM:  Some graphic modes do not look right.
SOLUTION: Either your VESA driver, your graphics card or your monitor does
          not support the selected resolution. If the resolution works under
          a non-VESA program (eg. Windows), the problem must be your VESA
          driver. Try installing another driver such as UNIVBE from SciTech.

PROBLEM:  When I start the program under Windows or with EMM386 installed,
          it crashes.
SOLUTION: LZA Desktop is not a Windows program. It is a protected mode DOS
          program. But you may be able to run it under these settings.
          However, linear access to the graphics card RAM does not seem to
          work. Try using the /B switch to disable linear frame buffer.
          Command line: LZA_DESK /B

PROBLEM:  I have some 320x200 animations, but LZA Desktop cannot view these on
          a full screen.
SOLUTION: Some of the dialog boxes used in LZA Desktop are larger than 320x200
          and therefore the program does not support this resolution. If you
          wish to see 320x200 animations on a full screen, you can use the
          command line utility PLAYLZA.


6. Compiling the Source Code
----------------------------

To compile the LZA player you need some files from the LZO v0.20 library
(newer version can possibly be used too). You can find the LZO library on
Oberhumer's WWW homepage: http://www.infosys.tuwien.ac.at/Staff/lux/marco).
The files you need are:

compr.h
config1c.h  
lzo1b_c.ch
lzo1b_cm.ch 
lzo1b_cr.ch 
lzo1b_d.ch  
lzo1b_de.h  
lzo1b_r.ch  
lzo1b_sm.ch 
lzo1b_tm.ch 
lzo1c.h     
lzo1c_9.c   
lzo1c_cc.c  
lzo1c_cc.h  
lzo1c_d1.c  
lzo1c_d2.c  
lzo1c_rr.c  
lzo1c_xx.c  
lzo1_d.h    
lzoconf.h   
lzo_conf.h  
lzo_defs.h  
lzo_dict.h  
lzo_lrun.h  
lzo_stat.h  
lzo_util.c  
lzo_util.h  
stats1b.h   
stats1c.h   

Note: In file lzo1c_xx.c you have to change line 36 - 43 into:
      &_lzo1c_9_compress_func


You will also need some files from Scitech's SVGA kit (available on SciTech's
ftp site: ftp.scitechsoft.com). I have used version 5.2, but newer versions
can probably be used too.
Here are the files you need:

debug.h
vesavbe.h
pmode.h     
pmode.lib   
svga.h
svga.lib


To compile with Watcom C for protected mode, use the following command line:
wcl386 /oneatx playlza draw lzo1c_cc lzo1c_xx lzo1c_d1 lzo1c_rr lzo1c_9
  lzo_util timer svga.lib pmode.lib


7. LZA Technical Specifications
-------------------------------

The following is a description of the LZA animation file format.
LZA is a shortcut for Lempel-Ziv-Oberhumer Compressed Animation


7.1. File format for LZA
------------------------

General header at the beginning of the file:

Size in bytes |Type     |Description
-----------------------------------------------------------------------
6             |Char     |File signature: "LZANIM"
1             |Byte     |Version (currently: 2)
2             |Word     |Number of frames in animation
2             |Word     |Screen width
2             |Word     |Screen height
4             |Longint  |Pause between frames (millisec.)


Following this header is the actual frames, each with a header:

Size in bytes |Type     |Description
-----------------------------------------------------------------------
1             |Byte     |Frame type, 1 = pixels, 2 = palette
2             |Word     |Number of blocks

A palette frame has just one block, containing the 6 bit RGB data for the
256 color palette. This is not compressed, so the palette size is
always 768 bytes.

NOTE: All animations should begin with a palette frame.
      There is no pause after palette frame, only after pixel frames,
      so if you wish to fade the palette slowly, you must include an
      skip-all-lines pixel frame after each palette frame.

The pixel blocks all have this header:

Size in bytes |Type     |Description
-----------------------------------------------------------------------
2             |Word     |Horizontal lines to skip
1             |Byte     |Block Type, 1 = LZO, 2 = SKIP
4             |LongInt  |Size of the compressed data block

NOTE: In version 1 of the LZA format, the block type is not part of the
      pixel block header. The only block type used in LZA v1 is LZO.

Skip block data:

Following the block header is the skip-compressed data block. It contains
a number of packets. Each packet starts with a skip-count byte. This number
of pixels can be skipped, since they are the same as the previous frame.
The next byte is a pixel count. This is the number of pixels to be drawn.
The color data for these pixels follows. Then the next packet follows.

LZO block data:

Following the block header, is the LZO compressed pixels in the block. The
compression scheme used is LZO1C-9 (see LZO note at the end of this file).


7.2. Implementation notes
-------------------------

If you want to write a LZA player, there is a few things to remember. First
of all, compared to flic, each line is NOT compressed individually. This
means that decompression directly to the screen, can only be done with
full screen animations. If you wish to play a non-full screen animation, or
scale an animation, you need to decompress each frame to a virtual screen,
before moving these data to the screen. You must also remember, that LZA
skips the horizontal lines that are exactly the same as on the previous
frame, so if you scale the animation, you must preserve the original frame.


Pseudo code for LZA version 2 player:

  Initialize player, open LZA file, read the LZA header.
  Check signature and version.
  Clear the screen.
  For each frame in the animation do:
    Read frame header.
    If frame is a palette frame:
      Read 768 byte palette data, and set palette.
    Else if frame is a pixel frame:
      For each block in pixel frame:
        Read block header.
        Skip the number of lines stated in the header.
        Read the block's compressed data.
        If the block is a LZO block:
          Decompress and show the data using LZO1C.
        Else if the block is a skip block:
          While there are compressed bytes left:
            Read the skip count, and skip this number of pixels.
            Read the number of uncompressed pixels.
            For all uncompressed pixels:
              Copy the pixel to screen
      Pause for the number of milliseconds stated in the LZA header.


7.3. Performance of LZA
-----------------------

When I designed LZA, my aim was to get a higher compression than FLI/FLC,
without reducing the replay speed too much. Compared to FLI/FLC, LZA
compresses better, when only a small part of a frame is repeated on the next
frame. The replay speed is generally a little slower than FLI/FLC, but with
an assembler implementation of the LZO1C-9 algorithm the replay speed could
probably be improved.

I have tested the LZA format with four FLI/FLC files. The files have the
following characteristics:
 - PC2.FLI: Every frame is almost completely different from the previous.
 - SPACE2.FLC: Most of the top and bottom of the frame is the same in each
   frame, while the center part changes.
 - HIRES.FLC: Three stars change size or move across the unchanging background.
 - CAR01.FLC: Small rotating car on black background.

Name       |FLI/FLC size  |LZA v1 size  |LZA v2 size  |
-------------------------------------------------------
PC2.FLI    |1376948 bytes |664886 bytes |665430 bytes |
SPACE2.FLC | 675776 bytes |505834 bytes |497683 bytes |
HIRES.FLC  | 231904 bytes |598154 bytes |277074 bytes |
CAR01.FLC  |  83214 bytes | 69820 bytes | 69892 bytes |

Name       |LZA v1 size compared to FLI/FLC |LZA v2 size compared to FLI/FLC
----------------------------------------------------------------------------
PC2.FLI    | 48.3 %                         | 48.3 %
SPACE2.FLC | 74.9 %                         | 73.6 %
HIRES.FLC  |257.9 %                         |119.5 %
CAR01.FLC  | 83.9 %                         | 84.0 %

The FLI/FLC files were created with Autodesk 3D Studio, while the LZA files
were created with the FLI2LZA utility. The LZA v1 compression used in FLI2LZA
is believed to be optimal in at least 99% of all animations with a resolution
of 320x200 or higher. The LZA v2 compression scheme used in FLI2LZA is
almost certainly not the optimal one very often, but it gives quite decent
results. I have fiddled around with the skip-percent setting in FLI2LZA to
find the best possible result. 80% was used with HIRES.FLC, 90% with PC2.FLI,
92% with SPACE2.FLC and 99% with CAR01.FLC.


7.4. LZO Note
-------------

The LZO1C-9 algoritm was invented by Markus Franz Xaver Johannes Oberhumer.
His C library for the LZO routines version 0.20 was released for Public Domain
the 11th of August 1996. Note that there are certain restrictions to the use
of the LZO library. These are stated in the GNU Library General Public
License version 2, June 1991.

His e-mail address is: markus.oberhumer@jk.uni-linz.ac.at
His WWW homepage address is: http://www.infosys.tuwien.ac.at/Staff/lux/marco
