ALLOCIMAGE(2)                                       ALLOCIMAGE(2)

     NAME
          allocimage, allocimagemix, freeimage, nameimage, namedimage,
          setalpha, loadimage, cloadimage, unloadimage, readimage,
          writeimage, bytesperline, wordsperline - allocating,
          freeing, reading, writing images

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <draw.h>

          Image *allocimage(Display *d, Rectangle r,
                ulong chan, int repl, ulong col)

          Image *allocimagemix(Display *d, ulong one, ulong three)

          int   freeimage(Image *i)

          int   nameimage(Image *i, char *name, int in)

          Image *namedimage(Display *d, char *name)

          ulong setalpha(ulong color, uchar alpha)

          int   loadimage(Image *i, Rectangle r, uchar *data, int ndata)

          int   cloadimage(Image *i, Rectangle r, uchar *data, int ndata)

          int   unloadimage(Image *i, Rectangle r, uchar *data, int ndata)

          Image *readimage(Display *d, int fd, int dolock)

          int   writeimage(int fd, Image *i, int dolock)

          int   bytesperline(Rectangle r, int d)

          int   wordsperline(Rectangle r, int d)

          enum
          {
              DOpaque             = 0xFFFFFFFF,
              DTransparent        = 0x00000000,
              DBlack              = 0x000000FF,
              DWhite              = 0xFFFFFFFF,
              DRed                = 0xFF0000FF,
              DGreen              = 0x00FF00FF,
              DBlue               = 0x0000FFFF,
              DCyan               = 0x00FFFFFF,
              DMagenta            = 0xFF00FFFF,
              DYellow             = 0xFFFF00FF,

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

     ALLOCIMAGE(2)                                       ALLOCIMAGE(2)

              DPaleyellow         = 0xFFFFAAFF,
              DDarkyellow         = 0xEEEE9EFF,
              DDarkgreen          = 0x448844FF,
              DPalegreen          = 0xAAFFAAFF,
              DMedgreen           = 0x88CC88FF,
              DDarkblue           = 0x000055FF,
              DPalebluegreen      = 0xAAFFFFFF,
              DPaleblue           = 0x0000BBFF,
              DBluegreen          = 0x008888FF,
              DGreygreen          = 0x55AAAAFF,
              DPalegreygreen      = 0x9EEEEEFF,
              DYellowgreen        = 0x99994CFF,
              DMedblue            = 0x000099FF,
              DGreyblue           = 0x005DBBFF,
              DPalegreyblue       = 0x4993DDFF,
              DPurpleblue         = 0x8888CCFF,

              DNotacolor          = 0xFFFFFF00,
              DNofill             = DNotacolor,

          };

     DESCRIPTION
          A new Image on Display d is allocated with allocimage; it
          will have the rectangle, pixel channel format, replication
          flag, and initial fill color given by its arguments.  Conve-
          nient pixel channels like GREY1, GREY2, CMAP8, RGB16, RGB24,
          and RGBA32 are predefined.  All the new image's pixels will
          have initial value col. If col is DNofill, no initialization
          is done.  Representative useful values of color are prede-
          fined: DBlack, DWhite, DRed, and so on.  Colors are speci-
          fied by 32-bit numbers comprising, from most to least sig-
          nificant byte, 8-bit values for red, green, blue, and alpha.
          The values correspond to illumination, so 0 is black and 255
          is white.  Similarly, for alpha 0 is transparent and 255 is
          opaque.  The id field will have been set to the identifying
          number used by /dev/draw (see draw(3)), and the cache field
          will be zero.  If repl is true, the clip rectangle is set to
          a very large region; if false, it is set to r. The depth
          field will be set to the number of bits per pixel specified
          by the channel descriptor (see image(6)). Allocimage returns
          0 if the server has run out of image memory.

          Allocimagemix is used to allocate background colors.  On 8-
          bit color-mapped displays, it returns a 2×2 replicated image
          with one pixel colored the color one and the other three
          with three. (This simulates a wider range of tones than can
          be represented by a single pixel value on a color-mapped
          display.)  On true color displays, it returns a 1×1 repli-
          cated image whose pixel is the result of mixing the two col-
          ors in a one to three ratio.

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

     ALLOCIMAGE(2)                                       ALLOCIMAGE(2)

          Freeimage frees the resources used by its argument image.

          Nameimage publishes in the server the image i under the
          given name. If in is non-zero, the image is published; oth-
          erwise i must be already named name and it is withdrawn from
          publication.  Namedimage returns a reference to the image
          published under the given name on Display d. These routines
          permit unrelated applications sharing a display to share an
          image; for example they provide the mechanism behind
          getwindow (see graphics(2)).

          The RGB values in a color are premultiplied by the alpha
          value; for example, a 50% red is 0x7F00007F not 0xFF00007F.
          The function setalpha performs the alpha computation on a
          given color, ignoring its initial alpha value, multiplying
          the components by the supplied alpha.  For example, to make
          a 50% red color value, one could execute setalpha(DRed,
          0x7F).

          The remaining functions deal with moving groups of pixel
          values between image and user space or external files.
          There is a fixed format for the exchange and storage of
          image data (see image(6)).

          Unloadimage reads a rectangle of pixels from image i into
          data, whose length is specified by ndata. It is an error if
          ndata is too small to accommodate the pixels.

          Loadimage replaces the specified rectangle in image i with
          the ndata bytes of data.

          The pixels are presented one horizontal line at a time,
          starting with the top-left pixel of r. In the data processed
          by these routines, each scan line starts with a new byte in
          the array, leaving the last byte of the previous line par-
          tially empty, if necessary.  Pixels are packed as tightly as
          possible within data, regardless of the rectangle being
          extracted.  Bytes are filled from most to least significant
          bit order, as the x coordinate increases, aligned so x=0
          would appear as the leftmost pixel of its byte.  Thus, for
          depth 1, the pixel at x offset 165 within the rectangle will
          be in a data byte at bit-position 0x04 regardless of the
          overall rectangle: 165 mod 8 equals 5, and 0x80 >> 5 equals
          0x04.

          Cloadimage does the same as loadimage, but for ndata bytes
          of compressed image data (see image(6)). On each call to
          cloadimage, the data must be at the beginning of a com-
          pressed data block, in particular, it should start with the
          y coordinate and data length for the block.

          Loadimage, cloadimage, and unloadimage return the number of

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

     ALLOCIMAGE(2)                                       ALLOCIMAGE(2)

          bytes copied.

          Readimage creates an image from data contained in an exter-
          nal file (see image(6) for the file format); fd is a file
          descriptor obtained by opening such a file for reading.  The
          returned image is allocated using allocimage. The dolock
          flag specifies whether the Display should be synchronized
          for multithreaded access; single-threaded programs can leave
          it zero.

          Writeimage writes image i onto file descriptor fd, which
          should be open for writing.  The format is as described for
          readimage.

          Readimage and writeimage do not close fd.

          Bytesperline and wordsperline return the number of bytes or
          words occupied in memory by one scan line of rectangle r in
          an image with d bits per pixel.

     EXAMPLE
          To allocate a single-pixel replicated image that may be used
          to paint a region red,
              red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);

     SOURCE
          /sys/src/libdraw

     SEE ALSO
          graphics(2), draw(2), draw(3), image(6)

     DIAGNOSTICS
          These functions return pointer 0 or integer -1 on failure,
          usually due to insufficient memory.

          May set errstr.

     BUGS
          Depth must be a divisor or multiple of 8.

     Page 4                       Plan 9             (printed 3/28/24)