allocimage(3) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/allocimage.html | 321 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 man/man3/allocimage.html (limited to 'man/man3/allocimage.html') diff --git a/man/man3/allocimage.html b/man/man3/allocimage.html new file mode 100644 index 00000000..d36fb0eb --- /dev/null +++ b/man/man3/allocimage.html @@ -0,0 +1,321 @@ + +allocimage(3) - Plan 9 from User Space + + + + +

ALLOCIMAGE(3) ALLOCIMAGE(3) +

+
+

NAME
+ +
+ + allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, + loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, + 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. Representative 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 2x2 replicated image with one + pixel colored 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 1x1 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(3)). + +
+ + 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 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(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 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 + compressed image data (see image(7)). 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 + copied. +
+ + 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 + occupied 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
+ +
+ + /usr/local/plan9/src/libdraw + +
+

SEE ALSO
+ +
+ + graphics(3), draw(3), draw(3), image(7)
+ +
+

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.
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3