PICOPEN(9.2)                                         PICOPEN(9.2)

     NAME
          picopen_r, picopen_w, picread, picwrite, picclose,
          rdpicfile, wrpicfile, picputprop, picgetprop, picunpack,
          picpack, picerror - picture file I/O

     SYNOPSIS
          #include <libg.h>

          #include <fb.h>

          PICFILE *picopen_r(char *name)

          PICFILE *picopen_w(char *name, char *type, int x0, int y0,
          int w, int h, char *chan, char *argv[], char *cmap)

          int picread(PICFILE *pf, char *buf)

          int picwrite(PICFILE *pf, char *buf)

          void picclose(PICFILE *pf)

          Bitmap *rdpicfile(PICFILE *pf, int ldepth)

          int wrpicfile(PICFILE *pf, Bitmap *b)

          PICFILE *picputprop(PICFILE *pf, char *name, char *value)

          char *picgetprop(PICFILE *pf, char *name)

          void picunpack(PICFILE *pf, char *pix, char *fmt, ...)

          void picpack(PICFILE *pf, char *pix, char *fmt, ...)

          void picerror(char *string)

     DESCRIPTION
          These functions read and write raster images in picfile(9.6)
          format.  They are loaded by option -lfb of 2l(1) et al.
          Open picture files are referred to by pointers of type
          PICFILE*.

          Picopen_r opens the named picfile for reading and returns a
          pointer to the open file.  If name is "IN", standard input
          is used.

          Picopen_w similarly creates the named image file for writ-
          ing.  The name "OUT" refers to standard output.  Type is a
          TYPE attribute, as described in picfile(9.6); x0 and y0 are
          the upper left coordinates of the WINDOW attribute; w and h
          are the image width and height in pixels.  Chan is a string

     Page 1                       Plan 9             (printed 10/1/20)

     PICOPEN(9.2)                                         PICOPEN(9.2)

          specifying the order of channels for the CHAN attribute; the
          length of this string becomes the value of NCHAN.  Argv, if
          nonzero, is conventionally the second argument of the main
          program; see exec(2). It becomes a COMMAND attribute record-
          ing the provenance of the file.

          The special call picopen_w( name, PIC_SAMEARGS(pf)) creates
          a file with the same attributes as an already open picfile.
          PIC_SAMEARGS mentions argv by name, hence the name must be
          in scope at the point of call.

          Picread and picwrite read or write a single row of pixels
          using the character array buf. The length of the row is
          determined from the file's WINDOW and NCHAN attributes.
          One-bit-per-pixel images (of type bitmap or ccitt-g4, for
          example) are decoded to one byte per pixel, 0 for black, 255
          for white, and are encoded as 1 for pixel values less than
          128 and 0 otherwise.  Files of type ccir601 are decoded into
          conventional rgb channels.

          Picclose closes a picfile and frees associated storage.

          Wrpicfile copies a bitmap into a picture file.  Rdpicfile
          allocates a Bitmap of given ldepth and reads picture file
          into it.  Since Bitmaps are usually monochrome and only one
          or two bits deep, rdpicfile computes the NTSC luminance of
          the input image and uses Floyd-Steinberg error-diffusion
          dither to hide quantization errors.

          Picputprop called after picopen_w but before picwrite adds
          header attributes, returning the revised PICFILE pointer.

          Picgetprop returns a pointer to the value of the named
          attribute, or 0 if the picfile does not have the attribute.
          In both Picputprop and picgetprop, with multiple appearances
          (e.g.  COMMAND) are expressed as a sequence of values sepa-
          rated by newlines.

          The header file defines macros to extract commonly-used
          attributes:

               PIC_NCHAN(pf), PIC_WIDTH(pf), PIC_HEIGHT(pf),
               PIC_SAMEARGS(pf) (see picopen_w)

          Picunpack extracts the channels of pixel array pix into sep-
          arate array args of types described by the fmt character
          string.  Format characters are c, s, l, f, d, for arrays of
          types unsigned char, short, long, float, and double.  Format
          character _ designates a picfile channel to be skipped.
          Picpack reverses the process.  These routines effect a stan-
          dard machine-independent byte ordering.

     Page 2                       Plan 9             (printed 10/1/20)

     PICOPEN(9.2)                                         PICOPEN(9.2)

          Picerror prints messages for errors resulting from calls to
          picfile routines.  (Perror(3) cannot describe some error
          conditions, like malformed header lines.)

     EXAMPLES
          Unpack the green and z channels from a file with channels
          rgbz...
               PICFILE *pf = picopen_r("file");
               extern char pixels[], green[][1000];
               extern float zdepth[][1000];
               for(i=0; picread(pf, pixels); i)
                    picunpack(pf, pixels, "_c_f", green[i], zdepth[i]);

          Reflect a picture about its vertical midline.
               PICFILE *in = picopen_r("picture");
               PICFILE *out = picopen_w("OUT", PIC_SAMEARGS(in));
               int w = PIC_WIDTH(in);
               int n = PIC_NCHAN(in);
               char *buffer = malloc(w*n), *temp = malloc(n);
               while (picread(in, buffer)) {
                    char *left = buffer;
                    char *right = buffer + n*(w - 1);
                    for( ; left<right; left+=n, right-=n) {
                         memmove(temp, left, n);
                         memmove(left, right, n);
                         memmove(right, temp, n);
                    }
                    picwrite(out, buffer);
               }

     SEE ALSO
          picfile(9.6)

     DIAGNOSTICS
          Picread returns 1 on success, 0 on end of file or error.
          Picopen_r and picopen_w return 0 for unopenable files.

     BUGS
          Picpack and picunpack store and retrieve floating point
          channels (types f and d) using native floating-point, rather
          than something transportable.

          The code required to support TYPE=ccir601 and the various
          ccitt fax compression types is missing!

     Page 3                       Plan 9             (printed 10/1/20)