RLE(5)                                                   RLE(5)





NAME
       rle - Run length encoded file format produced by the rle
       library

DESCRIPTION
       The output file format is (note: all words are 16  bits,
       and in PDP-11 byte order):

       Word 0 A  "magic"  number  0xcc52.   (Byte  order  0x52,
              0xcc.)

       Words 1-4
              The structure (chars saved in PDP-11 order)

              {
                  short   xpos,                       /* Lower left corner
                          ypos,
                          xsize,                      /* Size of saved box
                          ysize;
              }

       Byte 10
              (flags) The following flags are defined:

            H_CLEARFIRST
                   (0x1) If set,  clear  the  frame  buffer  to
                   background color before restoring.

            H_NO_BACKGROUND
                   (0x2)  If  set,  no background color is sup-
                   plied.  If  H_CLEARFIRST  is  also  set,  it
                   should   be  ignored  (or  alternatively,  a
                   clear-to-black  operation  could   be   per-
                   formed).

            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
                   ncolors.

            H_COMMENT
                   (0x8) If set, comments will follow the color
                   map in the header.

       Byte 11
              (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.

       Byte 12
              (pixelbits) Number of bits per pixel,  per  color
              channel.   Values  greater  than 8 currently will
              not work.

       Byte 13
              (ncmap) Number of  color  map  channels  present.
              Need  not  be  identical  to ncolors.  If this is
              non-zero, the color map follows immediately after
              the background colors.

       Byte 14
              (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.

       Bytes 15-...
              The background color.  There are ncolors bytes of
              background color.  If ncolors is even,  an  extra
              padding  byte  is  inserted  to  end  on a 16 bit
              boundary.  The background color is  only  present
              if  H_NO_BACKGROUND is not set in flags.  IF H_NO
              BACKGROUND is set, there is a single filler byte.
              Background  color  is  ignored,  but  present, if
              H_CLEARFIRST is not set in flags.

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

              If the 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 con-
              vention, of the form name=value, or just name.

              Following the setup information is the Run Length
              Encoded  image.   Each instruction consists of an
              opcode, a datum and possibly one or more  follow-
              ing 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:

       SkipLines (1)
              The datum is an unsigned number to  be  added  to
              the current Y position.

       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).

       SkipPixels (3)
              The datum is an unsigned number to  be  added  to
              the current X position.

       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.

       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.

       EOF (7)
              This  opcode  indicates  the logical end of image
              data.  A physical end-of-file will also serve  as
              well.   The EOF opcode may be used to concatenate
              several images in a single file.

SEE ALSO
       librle(3)

AUTHOR
       Spencer W. Thomas, Todd Fuqua



5                           9/14/82                      RLE(5)
