glenda.party
term% ls -F
term% cat index.txt
PICOPEN(9.2)                                                      PICOPEN(9.2)



NAME
       picopen_r,  picopen_w,  picread,  picwrite, picclose, rdpicfile, wrpic‐
       file, picputprop, picgetprop, picunpack, picpack - 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, ...)

DESCRIPTION
       These  functions  read  and write raster images in picfile(9.6) format.
       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 writing.  The name
       "OUT" refers to standard output.  Type is  a  TYPE  attribute,  as  de‐
       scribed  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 specifying the order of channels for the CHAN attri‐
       bute; 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 recording  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  con‐
       ventional rgb channels.

       Picclose closes a picture file 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 com‐
       putes 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 at‐
       tributes, 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 separated 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 separate 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
       standard machine-independent byte ordering.

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);
              }

SOURCE
       /sys/src/libfb

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.  All  three  set
       errstr(2) to explain their failure.

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

       There is no code to support TYPE=ccir601 and the various ccitt fax com‐
       pression types.



                                                                  PICOPEN(9.2)