IMAGE(6)                                                 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 machine-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 tex-
          tual string describing the pixel format (see strtochan in
          graphics(2) and the discussion 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 con-
          taining pixel r.max.x-1.  For images with depth d less than
          eight, a pixel with x-coordinate = x will appear as d con-
          tiguous bits in a byte, with the pixel's high order bit
          starting at the byte's bit number d*(x mod (8/d)), where
          bits within a byte are numbered 0 to 7 from the high order
          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 be a multiple 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 descriptions, 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 num-
          ber 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.

     Page 1                       Plan 9             (printed 3/19/24)

     IMAGE(6)                                                 IMAGE(6)

          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 particular '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 loga-
          rithm of the number of bits per pixel in the image.  In this
          case, ldepths 0, 1, 2, and 3 correspond to channel descrip-
          tors 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 uncom-
          pressed, is laid out in the usual form.

          The data is represented by a string of compression blocks,
          each encoding 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 includ-
          ing 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 Szy-
          manski `Data Compression via Textual Substitution', JACM
          29#4, pp. 928-951.

          The compression block is a string of variable-length code
          words encoding substrings of the pixel data.  A code word
          either gives the substring directly or indicates that it is
          a copy of data occurring previously 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

     Page 2                       Plan 9             (printed 3/19/24)

     IMAGE(6)                                                 IMAGE(6)

          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 48x48 face files as used by
          seemail (see faces(1) and face(6)) and 16x16 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 sepa-
          rately 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 deduce 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)

     Page 3                       Plan 9             (printed 3/19/24)