LRLE Pipeline Toolkit README
----------------------------

This archive contains a set of programs designed to emulate the
hardware implementation of LRLE.  The programs form a pipeline that
mirrors the operation of the hardware.

Included are source and a Makefile; this was originally developed on
a Windows machine under CYGWIN, but should compile and run fine on
a Linux machine as well.

FILES:

	Makefile	very simple makefile for all the component programs.
	bmp.h		header file for rudimentary BMP file operations

	rle_util.c	set of common routines for input, output, and
			parsing of the intermediate RLE formats that are
			passed between the programs.
	rle_util.h	header file for the above.

	cellsplit.c, lrle_engine.c, rle_greycomp.c, rle_reduce.c, 
	rle_runaccum.c, rle_format.c
			individual programs implementing the corresponding
			pipeline stages of the hardware implementation.

	rle_decode.c
			decoder for the output of rle_format.  Currently
			hard-wired for 16x16 cells (to be fixed).

	showraw.pl	A little Perl script for ascii-viewing 1- or 2-bit raw data.

PROGRAMS:
The pipeline is run as follows:
	cellsplit <input file.bmp> | lrle_engine | rle_greycomp |
		rle_reduce | rle_runaccum | rle_format > output.rle

Options can be added for the different modes, of course.

cellsplit
	This takes a BMP file and divides it into cells (tiles).
	Default size is 16x16; other sizes can be set with the -c
	option. The output format is pretty self-explanatory.

lrle_engine
	This performes the core LRLE function, taking raw pixel data
	from cellsplit and generating 16-bit RLE data for the later
	pipeline stages.  Parameters that may be set here are rMargin
	(-m, default 1), limit (-l, default 31), and use2d (-1 (off)
	or -2 (on), default "on").

rle_greycomp
	This translates pixel values to greyscale when appropriate, and
	places the resulting greyscale value in the GREEN field.  An
	indicator (GREY) is added to the pixel run to show its status.
	Parameters that may be set here are gMargin (-g<value>), gForce
	(-gF), and gDisable (-gD).

rle_reduce
	This translates the color value based on a selected mode.
	Presently, color modes of 15 and 7 bits, and greyscale modes
	from 1 to 6 bits are supported.  4-bit mode is to be added.

rle_runaccum
	This implements the run re-accumulator.  -r sets rLimit
	(default 31), while -c sets cLimit (default 255).

rle_format
	This performs the formatting for 1/2 bit raw modes, 3/4 bit
	compact RLE modes, and 7/15 bit RLE.  The command line sets
	the depth and whether it's grey or color. NOTE that the 
	formatter actually doesn't care whether it's grey or color;
	the information is only used to tell the decoder, which does
	care.

rle_decode
	This takes the output of rle_format and generates a BMP file.

EXAMPLES:
15-bit color:
	cellsplit in.bmp | lrle_engine | rle_greycomp |
		rle_reduce | rle_runaccum | rle_format >out.rle

7-bit color:
	cellsplit in.bmp | lrle_engine | rle_greycomp -g8 |
		rle_reduce -c7 | rle_runaccum | rle_format -c7 >out.rle

4-bit greyscale:
	cellsplit in.bmp | lrle_engine | rle_greycomp -gF |
		rle_reduce -g4 | rle_runaccum -r13 | rle_format -g4 >out.rle

3-bit greyscale:
	cellsplit in.bmp | lrle_engine -m2 | rle_greycomp -gF |
		rle_reduce -g3 | rle_runaccum -r27 | rle_format -g3 >out.rle

2-bit greyscale:
	cellsplit in.bmp | lrle_engine -1 -m2 | rle_greycomp -gF |
		rle_reduce -g2 | rle_runaccum -r<???> | rle_format -g2 >out.raw

1-bit greyscale:
	cellsplit in.bmp | lrle_engine -1 -m2 | rle_greycomp -gF |
		rle_reduce -g1 | rle_runaccum -r<???> | rle_format -g1 >out.raw

I/O FORMATS:
The output of each stage is pretty easy to read.  Here is a very brief
explanation of some of the highlights.

All programs output a "FILEINFO" block which contains basic info about the input
file and the cell size.  Rle_format does something different, in order to be
compatible with rle_decode, which came first.  My intention is to update 
rle_format and rle_decode to use the same header.

Cellsplit simply outputs raw pixel data, in hex, for each cell.

All other programs (except rle_format) output ASCII-formatted RLE data.  The 
format one of the following
	RUN  [GREY]  [RPT]  <runlength>  <red>,<green>,<blue>
	LC  <runlength>

@@@ Rolf @@@
changed that to 
        RUN <grey> <rpt> <runlenght> <red>,<green>,<blue>
to make it easier to parse w/o strcmp etc. in Verilog

There's actually only one space separating fields in the actual formats, but I
added an extra one here for readability.

For RUN, the optional "GREY" field is added (when appropriate) by rle_greycomp.
"RPT" is the opposite of isNew, and is added (when appropriate) by rle_runaccum.

In all cases, <runlength> is 0-based, so a value of 0 indicates 1 pixel, etc. 
