glenda.party
term% ls -F
term% cat index.txt
ALLOCIMAGE(2)                 System Calls Manual                ALLOCIMAGE(2)



NAME
       allocimage,  allocimagemix, freeimage, nameimage, namedimage, setalpha,
       loadimage, cloadimage, unloadimage,  readimage,  writeimage,  bytesper‐
       line, 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, int col)

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

       void  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,
           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, and  replication  flag  given  by  its
       arguments.   Convenient 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.  Rep‐
       resentative useful values of  color  are  predefined:  DBlack,  DWhite,
       DRed,  and  so  on.  Colors are specified by 32-bit numbers comprising,
       from most to least significant 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 col‐
       ored 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
       replicated  image whose pixel is the result of mixing the two colors in
       a one to three ratio.

       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; otherwise 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  setal‐
       pha(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 partially 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 left‐
       most  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  com‐
       pressed  image  data  (see  image(6)).  On each call to cloadimage, the
       data must be at the beginning of a compressed data block,  in  particu‐
       lar,  it  should  start  with  the y coordinate and data length for the
       block.

       Loadimage, cloadimage, and  unloadimage  return  the  number  of  bytes
       copied.

       Readimage creates an image from data contained in an external 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 occu‐
       pied 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.



                                                                 ALLOCIMAGE(2)