.\" Copyright (c) 1986, University of Utah
.TH RLE 5 9/14/82 5
.\" $Header: /usr/users/spencer/src/urt/man/man5/RCS/rle.5,v 3.0 90/08/03 15:33:11 spencer Exp $
.UC 4 
.SH NAME
rle \- Run length encoded file format produced by the rle library
.SH DESCRIPTION
The output file format is (note: all words are 16 bits, and in PDP-11 byte 
order):
.TP
.B Word 0
A "magic" number 0xcc52.  (Byte order 0x52, 0xcc.)
.TP
.B Words 1-4
The structure (chars saved in PDP-11 order)

.nf
{
    short   xpos,                       /* Lower left corner
            ypos,
            xsize,                      /* Size of saved box
            ysize;
}
.fi
.TP
.B Byte 10
.I (flags)
The following flags are defined:
.RS 0.5i
.TP
.I H_CLEARFIRST
(0x1) If set, clear the frame buffer to background color before restoring.
.TP
.I H_NO_BACKGROUND
(0x2) If set, no background color is supplied.  If
.I H_CLEARFIRST
is also set, it should be ignored (or alternatively, a clear-to-black
operation could be performed).
.TP
.I H_ALPHA
(0x4) If set, an alpha channel is saved as color channel -1.  The alpha
channel does not contribute to the count of colors in
.IR ncolors .
.TP
.I H_COMMENT
(0x8) If set, comments will follow the color map in the header.
.RE
.TP
.B Byte 11
.I (ncolors)
Number of color channels present.  0 means load only the color map (if
present), 1 means a B&W image, 3 means a normal color image.
.TP
.B Byte 12
.I (pixelbits)
Number of bits per pixel, per color channel.  Values greater than 8
currently will not work.
.TP
.B Byte 13
.I (ncmap)
Number of color map channels present.  Need not be identical to
.IR ncolors .
If this is non-zero, the color map follows immediately after the background
colors.
.TP
.B Byte 14
.I (cmaplen)
Log base 2 of the number of entries in the color map for each color channel.
I.e., would be 8 for a color map with 256 entries.
.TP
.B Bytes 15\-...
The background color.  There are 
.I ncolors
bytes of background color.  If
.I ncolors
is even, an extra padding byte is inserted to end on a 16 bit boundary.
The background color is only present if
.I H_NO_BACKGROUND
is not set in
.IR flags .
IF
.I H_NO BACKGROUND
is set, there is a single filler byte.  Background color is ignored, but
present, if
.I H_CLEARFIRST
is not set in
.IR flags .

If 
.I ncmap
is non-zero, then the color map will follow as
.IR ncmap *2^ cmaplen
16 bit words.  The color map data is left justified in each word.

If the
.I H_COMMENT
flag is set, a set of comments will follow.  The first 16 bit word
gives the length of the comments in bytes.  If this is odd, a filler
byte will be appended to the comments.  The comments are interpreted
as a sequence of null terminated strings which should be, by
convention, of the form
.IR name = value ,
or just
.IR name .

Following the setup information is the Run Length Encoded image.  Each
instruction consists of an opcode, a datum and possibly one or
more following words (all words are 16 bits).  The opcode is encoded in the
first byte of the instruction word.  Instructions come in either a short or
long form.  In the short form, the datum is in the second byte of the
instruction word; in the long form, the datum is a 16 bit value in the word
following the instruction word.  Long form instructions are distinguished by
having the 0x40 bit set in the opcode byte.
The instruction opcodes are:
.TP
.B SkipLines (1)
The datum is an unsigned number to be added to the current Y position.
.TP
.B SetColor (2)
The datum indicates which color is to be loaded with the data described by the
following ByteData and RunData instructions.  Typically,
0\(->red, 1\(->green, 2\(->blue.  The
operation also resets the X position to the initial X (i.e. a carriage return
operation is performed).
.TP
.B SkipPixels (3)
The datum is an unsigned number to be added to the current X
position.
.TP
.B ByteData (5)
The datum is one less than the number of bytes of color data following.  If the
number of bytes is odd, a filler byte will be appended to the end of the byte
string to make an integral number of 16-bit words.  The X position is
incremented to follow the last byte of data.
.TP
.B RunData (6)
The datum is one less than the run length.  The following word contains (in its
lower 8 bits) the color of the run.  The X position is incremented to follow
the last byte in the run.
.TP
.B EOF (7)
This opcode indicates the logical end of image data.  A physical
end-of-file will also serve as well.  The 
.B EOF
opcode may be used to concatenate several images in a single file.
.SH SEE ALSO
.I librle(3)
.SH AUTHOR
.PP 
Spencer W. Thomas, Todd Fuqua