glenda.party
term% ls -F
term% cat index.txt
IMAGE(6)                         Games Manual                         IMAGE(6)



NAME
       image - external format for images

SYNOPSIS
       #include <draw.h>

DESCRIPTION
       Images are described in graphics(2), and the definition of pixel values
       is in color(6).  Fonts and images are stored in external files  in  ma‐
       chine-independent formats.

       Image  files  are  read and written using readimage and writeimage (see
       allocimage(2)),or readmemimage and writememimage (see memdraw(2)).   An
       uncompressed  image file starts with 5 strings: chan, r.min.x, r.min.y,
       r.max.x, and r.max.y.  Each is right-justified and blank padded  in  11
       characters,  followed  by  a blank.  The chan value is a textual string
       describing the pixel format (see strtochan in graphics(2) and the  dis‐
       cussion  of  channel  descriptors below), and the rectangle coordinates
       are decimal strings.  The rest of the file contains the r.max.y-r.min.y
       rows  of  pixel  data.   A  row  consists  of the byte containing pixel
       r.min.x and all the bytes up to and including the byte containing pixel
       r.max.x-1.  For images with depth d less than eight, a pixel with x-co‐
       ordinate = x will appear as d contiguous  bits  in  a  byte,  with  the
       pixel's  high  order  bit  starting  at  the byte's bit number w*(x mod
       (8/w)), where bits within a byte are numbered 0 to 7 from the high  or‐
       der  to  the  low order bit.  Rows contain integral number of bytes, so
       there may be some unused pixels at either  end  of  a  row.   If  d  is
       greater than 8, the definition of images requires that it will a multi‐
       ple of 8, so pixel values take up an integral number of bytes.

       The loadimage and unloadimage functions described in allocimage(2) also
       deal with rows in this format, stored in user memory.

       The  channel  format  string is a sequence of two-character channel de‐
       scriptions, each comprising a letter (r for red, g  for  green,  b  for
       blue,  a  for  alpha,  m  for  color-mapped, k for greyscale, and x for
       ``don't care'') followed by a number of bits per pixel.  The sum of the
       channel  bits per pixel is the depth of the image, which must be either
       a divisor or a multiple of eight.  It is an error to have more than one
       of any channel but x.  An image must have either a greyscale channel; a
       color mapped channel; or red, green, and blue channels.  If  the  alpha
       channel is present, it must be at least as deep as any other channel.

       The  channel  string  defines the format of the pixels in the file, and
       should not be confused with ordering of bytes in the file.  In particu‐
       lar  'r8g8b8' pixels have byte ordering blue, green, and red within the
       file.  See color(6) for more details of the pixel format.

       A venerable yet deprecated format replaces the channel  string  with  a
       decimal  ldepth,  which is the base two logarithm of the number of bits
       per pixel in the image.  In this case, ldepths 0, 1, 2,  and  3  corre‐
       spond to channel descriptors k1, k2, k4, and m8, respectively.

       Compressed  image  files  start with a line of text containing the word
       compressed, followed by a header as described above,  followed  by  the
       image  data.   The  data,  when  uncompressed, is laid out in the usual
       form.

       The data is represented by a string of compression blocks, each  encod‐
       ing a number of rows of the image's pixel data.  Compression blocks are
       at most 6024 bytes long, so that they fit comfortably in  a  single  9P
       message.  Since a compression block must encode a whole number of rows,
       there is a limit (about 5825 bytes) to the width of images that may  be
       encoded.   Most  wide images are in subfonts, which, at 1 bit per pixel
       (the usual case for fonts), can be 46600 pixels wide.

       A compression block begins with two decimal  strings  of  twelve  bytes
       each.   The  first number is one more than the y coordinate of the last
       row in the block.  The second is the number of bytes of compressed data
       in  the block, not including the two decimal strings.  This number must
       not be larger than 6000.

       Pixels are encoded using a version of Lempel  &  Ziv's  sliding  window
       scheme  LZ77,  best  described in J A Storer & T G Szymanski `Data Com‐
       pression via Textual Substitution', JACM 29#4, pp. 928-951.

       The compression block is a string of variable-length code words  encod‐
       ing  substrings  of  the pixel data.  A code word either gives the sub‐
       string directly or indicates that it is a copy of data occurring previ‐
       ously in the pixel stream.

       In a code word whose first byte has the high-order bit set, the rest of
       the byte indicates the length of a substring encoded directly.   Values
       from 0 to 127 encode lengths from 1 to 128 bytes.  Subsequent bytes are
       the literal pixel data.

       If the high-order bit is zero, the next 5 bits encode the length  of  a
       substring  copied  from  previous  pixels.   Values from 0 to 31 encode
       lengths from 3 to 34 bytes.  The bottom two bits of the first byte  and
       the  8 bits of the next byte encode an offset backward from the current
       position in the pixel data at which the copy is to  be  found.   Values
       from  0  to  1023  encode  offsets from 1 to 1024.  The encoding may be
       `prescient', with the length larger than the offset, which  works  just
       fine:  the  new data is identical to the data at the given offset, even
       though the two strings overlap.

       Some small images, in particular 48×48 face files as  used  by  seemail
       (see  faces(1) and face(6)) and 16×16 cursors, can be stored textually,
       suitable for inclusion in C source.  Each line of text  represents  one
       scan  line  as a comma-separated sequence of hexadecimal bytes, shorts,
       or words in C format.  For cursors, each line defines a pair of  bytes.
       (It takes two images to define a cursor; each must be stored separately
       to be processed by programs such as tweak(1).)  Face files of  one  bit
       per  pixel  are  stored  as a sequence of shorts, those of larger pixel
       sizes as a sequence of longs.  Software that reads these files must de‐
       duce  the image size from the input; there is no header.  These formats
       reflect history rather than design.

SEE ALSO
       jpg(1),  tweak(1),  graphics(2),  draw(2),   allocimage(2),   color(6),
       face(6), font(6)



                                                                      IMAGE(6)