diff options
Diffstat (limited to 'man/man3/allocimage.html')
| -rw-r--r-- | man/man3/allocimage.html | 321 |
1 files changed, 321 insertions, 0 deletions
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 @@ +<head> +<title>allocimage(3) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>ALLOCIMAGE(3)</b><td align=right><b>ALLOCIMAGE(3)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, + loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, + wordsperline – allocating, freeing, reading, writing images<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#include <u.h><br> + #include <libc.h><br> + #include <draw.h><br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Image *allocimage(Display *d, Rectangle r, <br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + ulong chan, int repl, int col)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + </table> + + </table> + </font></tt> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + + + </table> + + </table> + <tt><font size=+1>Image *allocimagemix(Display *d, ulong one, ulong three)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>void freeimage(Image *i)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int nameimage(Image *i, char *name, int in)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Image *namedimage(Display *d, char *name)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>ulong setalpha(ulong color, uchar alpha)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int loadimage(Image *i, Rectangle r, uchar *data, int ndata)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int cloadimage(Image *i, Rectangle r, uchar *data, int ndata)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int unloadimage(Image *i, Rectangle r, uchar *data, int ndata)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Image *readimage(Display *d, int fd, int dolock)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int writeimage(int fd, Image *i, int dolock)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int bytesperline(Rectangle r, int d)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int wordsperline(Rectangle r, int d)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>enum<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + DOpaque = 0xFFFFFFFF,<br> + DTransparent = 0x00000000,<br> + DBlack = 0x000000FF,<br> + DWhite = 0xFFFFFFFF,<br> + DRed = 0xFF0000FF,<br> + DGreen = 0x00FF00FF,<br> + DBlue = 0x0000FFFF,<br> + DCyan = 0x00FFFFFF,<br> + DMagenta = 0xFF00FFFF,<br> + DYellow = 0xFFFF00FF,<br> + DPaleyellow = 0xFFFFAAFF,<br> + DDarkyellow = 0xEEEE9EFF,<br> + DDarkgreen = 0x448844FF,<br> + DPalegreen = 0xAAFFAAFF,<br> + DMedgreen = 0x88CC88FF,<br> + DDarkblue = 0x000055FF,<br> + DPalebluegreen = 0xAAFFFFFF,<br> + DPaleblue = 0x0000BBFF,<br> + DBluegreen = 0x008888FF,<br> + DGreygreen = 0x55AAAAFF,<br> + DPalegreygreen = 0x9EEEEEFF,<br> + DYellowgreen = 0x99994CFF,<br> + DMedblue = 0x000099FF,<br> + DGreyblue = 0x005DBBFF,<br> + DPalegreyblue = 0x4993DDFF,<br> + DPurpleblue = 0x8888CCFF,<br> + DNotacolor = 0xFFFFFF00,<br> + DNofill = DNotacolor,<br> + <br> + + </table> + };<br> + </font></tt> +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + A new <tt><font size=+1>Image</font></tt> on <tt><font size=+1>Display d</font></tt> is allocated with <tt><font size=+1>allocimage</font></tt>; it will + have the rectangle, pixel channel format, and replication flag + given by its arguments. Convenient pixel channels like <tt><font size=+1>GREY1</font></tt>, + <tt><font size=+1>GREY2</font></tt>, <tt><font size=+1>CMAP8</font></tt>, <tt><font size=+1>RGB16</font></tt>, <tt><font size=+1>RGB24</font></tt>, and <tt><font size=+1>RGBA32</font></tt> are predefined. All the + new image’s pixels will have initial value <i>col</i>. If <i>col + </i>is <tt><font size=+1>DNofill</font></tt>, no initialization is done. Representative useful values + of color are predefined: <tt><font size=+1>DBlack</font></tt>, <tt><font size=+1>DWhite</font></tt>, <tt><font size=+1>DRed</font></tt>, 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 <i>id</i> field will have been set to the identifying + number used by <tt><font size=+1>/dev/draw</font></tt> (see <a href="../man3/draw.html"><i>draw</i>(3)</a>), and the <i>cache</i> field will + be zero. If <i>repl</i> is true, the clip rectangle is set to a very + large region; if false, it is set to <i>r</i>. The <i>depth</i> field will be + set to the + number of bits per pixel specified by the channel descriptor (see + <a href="../man7/image.html"><i>image</i>(7)</a>). <i>Allocimage</i> returns 0 if the server has run out of image + memory. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Allocimagemix</i> is used to allocate background colors. On 8-bit + color-mapped displays, it returns a 2x2 replicated image with one + pixel colored the color <i>one</i> and the other three with <i>three</i>. (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. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Freeimage</i> frees the resources used by its argument image. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Nameimage</i> publishes in the server the image <i>i</i> under the given + <i>name</i>. If <i>in</i> is non-zero, the image is published; otherwise <i>i</i> must + be already named <i>name</i> and it is withdrawn from publication. <i>Namedimage</i> + returns a reference to the image published under the given <i>name</i> + on <tt><font size=+1>Display</font></tt> <i>d</i>. These routines permit + unrelated applications sharing a display to share an image; for + example they provide the mechanism behind <tt><font size=+1>getwindow</font></tt> (see <a href="../man3/graphics.html"><i>graphics</i>(3)</a>). + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The RGB values in a color are <i>premultiplied</i> by the alpha value; + for example, a 50% red is <tt><font size=+1>0x7F00007F</font></tt> not <tt><font size=+1>0xFF00007F</font></tt>. The function + <i>setalpha</i> performs the alpha computation on a given <tt><font size=+1>color</font></tt>, ignoring + its initial alpha value, multiplying the components by the supplied + <tt><font size=+1>alpha</font></tt>. For example, to make a 50% red + color value, one could execute <tt><font size=+1>setalpha(DRed, 0x7F)</font></tt>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + 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 <a href="../man7/image.html"><i>image</i>(7)</a>). + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Unloadimage</i> reads a rectangle of pixels from image <i>i</i> into <i>data</i>, + whose length is specified by <i>ndata</i>. It is an error if <i>ndata</i> is + too small to accommodate the pixels. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Loadimage</i> replaces the specified rectangle in image <i>i</i> with the + <i>ndata</i> bytes of <i>data</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The pixels are presented one horizontal line at a time, starting + with the top-left pixel of <i>r</i>. 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 <i>data</i>, regardless + of + the rectangle being extracted. Bytes are filled from most to least + significant bit order, as the <i>x</i> coordinate increases, aligned + so <i>x</i>=0 would appear as the leftmost pixel of its byte. Thus, for + <tt><font size=+1>depth</font></tt> 1, the pixel at <i>x</i> offset 165 within the rectangle will be + in a <i>data</i> byte at bit-position <tt><font size=+1>0x04</font></tt> regardless of the overall + rectangle: 165 mod 8 equals 5, and <tt><font size=+1>0x80 >> 5</font></tt> equals <tt><font size=+1>0x04</font></tt>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>Cloadimage</font></tt> does the same as <i>loadimage</i>, but for <i>ndata</i> bytes of + compressed image <i>data</i> (see <a href="../man7/image.html"><i>image</i>(7)</a>). On each call to <i>cloadimage,</i> + the <i>data</i> must be at the beginning of a compressed data block, + in particular, it should start with the <tt><font size=+1>y</font></tt> coordinate and data + length for the block. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Loadimage</i>, <i>cloadimage</i>, and <i>unloadimage</i> return the number of bytes + copied. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Readimage</i> creates an image from data contained in an external + file (see <a href="../man7/image.html"><i>image</i>(7)</a> for the file format); <i>fd</i> is a file descriptor + obtained by opening such a file for reading. The returned image + is allocated using <i>allocimage</i>. The <i>dolock</i> flag specifies whether + the <tt><font size=+1>Display</font></tt> should be synchronized for multithreaded access; + single-threaded programs can leave it zero. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Writeimage</i> writes image <i>i</i> onto file descriptor <i>fd</i>, which should + be open for writing. The format is as described for <i>readimage</i>. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Readimage</i> and <i>writeimage</i> do not close <i>fd</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Bytesperline</i> and <i>wordsperline</i> return the number of bytes or words + occupied in memory by one scan line of rectangle <i>r</i> in an image + with <i>d</i> bits per pixel.<br> + +</table> +<p><font size=+1><b>EXAMPLE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + To allocate a single-pixel replicated image that may be used to + paint a region red,<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);<br> + </font></tt> + </table> + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/libdraw<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man3/graphics.html"><i>graphics</i>(3)</a>, <a href="../man3/draw.html"><i>draw</i>(3)</a>, <a href="../man3/draw.html"><i>draw</i>(3)</a>, <a href="../man7/image.html"><i>image</i>(7)</a><br> + +</table> +<p><font size=+1><b>DIAGNOSTICS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + These functions return pointer 0 or integer –1 on failure, usually + due to insufficient memory. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + May set <i>errstr</i>.<br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>Depth</font></tt> must be a divisor or multiple of 8.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |