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