Google Git
Sign in
plan9port / plan9 / 1ac1981659ba7abcc1c76436e4b4dfc2bc616d2a / . / man / man3 / allocimage.html
blob: d36fb0eb5d63eeb0d4d230b1093ed1fb70eba767 [file] [log] [blame]
<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 &ndash; 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 &lt;u.h&gt;<br>
#include &lt;libc.h&gt;<br>
#include &lt;draw.h&gt;<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 &nbsp;&nbsp;&nbsp;freeimage(Image *i)<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xFFFFFFFF,<br>
DTransparent &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x00000000,<br>
DBlack &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x000000FF,<br>
DWhite &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xFFFFFFFF,<br>
DRed &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xFF0000FF,<br>
DGreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x00FF00FF,<br>
DBlue &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x0000FFFF,<br>
DCyan &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x00FFFFFF,<br>
DMagenta &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xFF00FFFF,<br>
DYellow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xFFFF00FF,<br>
DPaleyellow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xFFFFAAFF,<br>
DDarkyellow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xEEEE9EFF,<br>
DDarkgreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x448844FF,<br>
DPalegreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xAAFFAAFF,<br>
DMedgreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x88CC88FF,<br>
DDarkblue &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x000055FF,<br>
DPalebluegreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xAAFFFFFF,<br>
DPaleblue &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x0000BBFF,<br>
DBluegreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x008888FF,<br>
DGreygreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x55AAAAFF,<br>
DPalegreygreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x9EEEEEFF,<br>
DYellowgreen &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x99994CFF,<br>
DMedblue &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x000099FF,<br>
DGreyblue &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x005DBBFF,<br>
DPalegreyblue &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x4993DDFF,<br>
DPurpleblue &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0x8888CCFF,<br>
DNotacolor &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 0xFFFFFF00,<br>
DNofill &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= 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&#8217;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 &gt;&gt; 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 &ndash;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>