Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ALLOCIMAGE(3)		   Library Functions Manual		 ALLOCIMAGE(3)

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

       #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)

	   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,


       A new Image on Display d	is allocated with allocimage; it will have the
       rectangle, pixel	channel	format,	and replication	flag given by its  ar-
       guments.	  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 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	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 2A2 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  1A1
       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

       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,

       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

       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 On each call to cloadimage, the data must be at
       the beginning of	a compressed 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 bytes

       Readimage creates an image from data contained in an external file (see
       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.

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


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

       May set errstr.

       Depth must be a divisor or multiple of 8.



Want to link to this manual page? Use this URL:

home | help