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 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(7)).  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 image(7)).

       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(7)).  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

       Loadimage,  cloadimage,	and  unloadimage  return  the  number of bytes

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


       graphics(3), draw(3), draw(3), image(7)

       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