1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
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>
|