321 lines
18 KiB
HTML
321 lines
18 KiB
HTML
<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>
|