LIBRLE(3V)

NAME
librle - run-length encoded image library

SYNOPSIS
#include ``/vld/include/rle.h''
#include ``/vld/include/fb.h''

int rle_rhdr( stream, flags, bgpixel )
FILE *stream;
int *flags;
Pixel *bgpixel;

rle_whdr( stream, ncolors, bgflag, cmflag, bgpixel )
FILE *stream;
Pixel *bgpixel;

rle_rlen( xlen, ylen )
int *xlen, *ylen;

rle_rpos( xpos, ypos )
int *xpos, *ypos;

rle_wlen( xlen, ylen, mode )
int xlen, ylen, mode;

rle_wpos( xpos, ypos, mode )
int xpos, ypos, mode;

int rle_rmap( stream, cmap )
FILE *stream;
ColorMap *cmap;

rle_wmap( stream, cmap )
FILE *stream;
ColorMap *cmap;

rle_decode_ln( stream, scanline_buffer )
FILE *stream;
Pixel *scanline_buffer;

rle_encode_ln( stream, scanline_buffer )
FILE *stream;
Pixel *scanline_buffer;

DESCRIPTION
These routines are designed to provide a means of decoding or encoding University of Utah Alpha_1 format Run-Length Encoded (RLE) files from a C program. There are separate routines for reading or writing the RLE header, reading or writing the encoded color map, and decoding or encoding a scanline of a raster image. The program that loads this library can be ignorant of the particular encoding scheme being used. This library does not need to know anything about the available frame buffer hardware. The frame buffer library, libfb(3V), can also be used to free programs of hardware dependence.

The following routines are used to decode an RLE file into a raster image:

Rle_rhdr will seek to the beginning of the given input stream and read the setup information in the RLE header. This routine must be called first when decoding an RLE file. If bgpixel is not NULL, the background color stored in the RLE header will be placed there. Flags is a flag word using a combination of single-bit flags NO_BOX_SAVE, NO_COLORMAP, and NO_IMAGE (described in rle.h) to indicate whether the image was saved with background, whether the color map was saved, and whether the image was saved or just the color map. If the color map was saved, rle_rmap must be used next to read the color map from the RLE file and decode it into the buffer pointed to by cmap. Rle_rlen and rle_rpos are used after rle_rhdr to retrieve, from the header structure, the length and position of the image in the locations specified by xlen, ylen, xpos and ypos.

Rle_decode_ln is used to decode the next scanline (starting at the bottom) and should be passed the address of a scanline_buffer large enough to store xlen plus xpos pixels. Only foreground pixels are written; it is the caller's responsibility to fill the buffer first with the appropriate background. If no foreground pixels occur, zero is returned; otherwise 1 is returned to indicate that the buffer has been altered.

The following routines are used to compress a raster image into an RLE file:

Rle_whdr is used first to specify the encoding scheme to use and to write the RLE header which will contain this information to the given output stream. The ncolors parameter specifies the number of color channels. Normally, this should be set to 3 (for red, green, and blue channels). If ncolors equals 1, a monochrome (black and white) image is assumed, and if it is 0, only the color map will be saved. Bgflag specifies whether or not the image is saved with the background. If bgflag is nonzero, only the foreground image is saved. If bgflag is zero, the entire image is encoded. Rle_whdr stores the background color along with the other setup information. If a monochrome image has been specified, the NTSC standard is used to calculate the background color from bgpixel; otherwise bgpixel is used as the background color. Cmflag is nonzero to indicate that the color map is to be saved, and this is accomplished with rle_wmap which must be used next to encode the color map pointed to by cmap and write it to the RLE file. If the value of cmap is NULL, a standard (linear) color map will be written.

Rle_encode_ln is used to encode the next scanline (starting at the bottom) and should be passed the address of a scanline_buffer containing the pixels to be converted.

The Pixel and ColorMap data types are defined in fb.h. The color map and scanlines can be conveniently read from or written to a file or supported frame buffer with compatible functions found in libfb(3V).

WARNINGS
The RLE files must be decoded seqentially from the bottom up, as it is the convention that the origin be the lower left corner of the screen. Rle_decode_ln should fail if called more than ylen times, as it will attempt to read past the end of the input file. Encoding an RLE file from the top down is considered anti-social behavior and will lead to confusion if the installed frame buffer utilities are used. The functions must be used in sequence to read/write the header, followed by the color map (if one exists) and then the image. It is safe to process multiple images as long as the proper sequence is followed. Both rle_rhdr and rle_whdr seek to the beginning of stream before performing any I/O, but all other functions rely on sequential read/write operations on the RLE file.

Processing two images asynchronously is not recommended; that is, you should finish one before you begin the next. The problem stems from the fact that some global information is stored by rle_rhdr, and this information is clobbered by subsequent calls. Therefore, when switching back to an image that is partially decoded, the file offset must be determined with ftell(3S); then rle_rhdr can be invoked again to set up things, and finally fseek(3S) can be used to reposition the file pointer.

EXAMPLE
The library may be loaded as follows:
    $ cc -I/vld/include program.c vld/lib/librle.a

FILES
/vld/include/rle.h
/vld/include/fb.h
/vld/lib/librle.a

SEE ALSO
libfb(3V).

DIAGNOSTICS
Upon error, all functions print a message and return -1.

AUTHOR
Gary S. Moss, BRL/VLD-VMB
Mike J. Muuss, BRL/SECAD
Spencer W. Thomas, U. of Utah

BUGS
It would be nice to fix the problem of asynchronous calls by passing a pointer to storage for the setup structure to the read/write header and read/write scanline routines so that there is no global information to contend with.