allocimage man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

ALLOCIMAGE(2)							 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)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net