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, 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,
           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.  Convenient pixel channels like GREY1,
       GREY2, CMAP8, RGB16, RGB24, and RGBA32 are predefined.  All the new im‐
       age's  pixels  will have initial value col.  If col is DNofill, no ini‐
       tialization is done.  Representative useful values of color are  prede‐
       fined: 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 illumina‐
       tion, so 0 is black and 255 is white.  Similarly, for alpha 0 is trans‐
       parent and 255 is opaque.  The id field will have been set to the iden‐
       tifying 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 ex‐
       ample, 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 ex‐
       ample,  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 partially empty, if necessary.  Pixels are packed  as
       tightly  as possible within data, regardless of the rectangle being ex‐
       tracted.  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  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)