tallocimage.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tallocimage.3 (7311B)
---
1 .TH ALLOCIMAGE 3
2 .SH NAME
3 allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline \- allocating, freeing, reading, writing images
4 .SH SYNOPSIS
5 .nf
6 .PP
7 .B
8 #include <u.h>
9 .B
10 #include <libc.h>
11 .B
12 #include <draw.h>
13 .PP
14 .ta \w'\fLImage 'u
15 .B
16 Image *allocimage(Display *d, Rectangle r,
17 .br
18 .B
19 ulong chan, int repl, int col)
20 .PP
21 .B
22 Image *allocimagemix(Display *d, ulong one, ulong three)
23 .PP
24 .B
25 void freeimage(Image *i)
26 .PP
27 .B
28 int nameimage(Image *i, char *name, int in)
29 .PP
30 .B
31 Image *namedimage(Display *d, char *name)
32 .PP
33 .B
34 ulong setalpha(ulong color, uchar alpha)
35 .PP
36 .B
37 int loadimage(Image *i, Rectangle r, uchar *data, int ndata)
38 .PP
39 .B
40 int cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
41 .PP
42 .B
43 int unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
44 .PP
45 .B
46 Image *readimage(Display *d, int fd, int dolock)
47 .PP
48 .B
49 int writeimage(int fd, Image *i, int dolock)
50 .PP
51 .B
52 int bytesperline(Rectangle r, int d)
53 .PP
54 .B
55 int wordsperline(Rectangle r, int d)
56 .PP
57 .nf
58 .B
59 enum
60 .nf
61 .ft L
62 .ta +4n +20
63 {
64 DOpaque = 0xFFFFFFFF,
65 DTransparent = 0x00000000,
66 DBlack = 0x000000FF,
67 DWhite = 0xFFFFFFFF,
68 DRed = 0xFF0000FF,
69 DGreen = 0x00FF00FF,
70 DBlue = 0x0000FFFF,
71 DCyan = 0x00FFFFFF,
72 DMagenta = 0xFF00FFFF,
73 DYellow = 0xFFFF00FF,
74 DPaleyellow = 0xFFFFAAFF,
75 DDarkyellow = 0xEEEE9EFF,
76 DDarkgreen = 0x448844FF,
77 DPalegreen = 0xAAFFAAFF,
78 DMedgreen = 0x88CC88FF,
79 DDarkblue = 0x000055FF,
80 DPalebluegreen = 0xAAFFFFFF,
81 DPaleblue = 0x0000BBFF,
82 DBluegreen = 0x008888FF,
83 DGreygreen = 0x55AAAAFF,
84 DPalegreygreen = 0x9EEEEEFF,
85 DYellowgreen = 0x99994CFF,
86 DMedblue = 0x000099FF,
87 DGreyblue = 0x005DBBFF,
88 DPalegreyblue = 0x4993DDFF,
89 DPurpleblue = 0x8888CCFF,
90
91 DNotacolor = 0xFFFFFF00,
92 DNofill = DNotacolor,
93
94 };
95 .fi
96 .SH DESCRIPTION
97 A new
98 .B Image
99 on
100 .B Display
101 .B d
102 is allocated with
103 .BR allocimage ;
104 it will have the rectangle, pixel channel format,
105 and replication flag
106 given by its arguments.
107 Convenient pixel channels like
108 .BR GREY1 ,
109 .BR GREY2 ,
110 .BR CMAP8 ,
111 .BR RGB16 ,
112 .BR RGB24 ,
113 and
114 .BR RGBA32
115 are predefined.
116 All the new image's pixels will have initial value
117 .IR col .
118 If
119 .I col
120 is
121 .BR DNofill ,
122 no initialization is done.
123 Representative useful values of color are predefined:
124 .BR DBlack ,
125 .BR DWhite ,
126 .BR DRed ,
127 and so on.
128 Colors are specified by 32-bit numbers comprising,
129 from most to least significant byte,
130 8-bit values for red, green, blue, and alpha.
131 The values correspond to illumination, so 0 is black and 255 is white.
132 Similarly, for alpha 0 is transparent and 255 is opaque.
133 The
134 .I id
135 field will have been set to the identifying number used by
136 .B /dev/draw
137 (see
138 .MR draw (3) ),
139 and the
140 .I cache
141 field will be zero.
142 If
143 .I repl
144 is true, the clip rectangle is set to a very large region; if false, it is set to
145 .IR r .
146 The
147 .I depth
148 field will be set to the number of bits per pixel specified
149 by the channel descriptor
150 (see
151 .MR image (7) ).
152 .I Allocimage
153 returns 0 if the server has run out of image memory.
154 .PP
155 .I Allocimagemix
156 is used to allocate background colors.
157 On 8-bit color-mapped displays, it
158 returns a 2×2 replicated image with one pixel colored
159 the color
160 .I one
161 and the other three with
162 .IR three .
163 (This simulates a wider range of tones than can be represented by a single pixel
164 value on a color-mapped display.)
165 On true color displays, it returns a 1×1 replicated image
166 whose pixel is the result of mixing the two colors in
167 a one to three ratio.
168 .PP
169 .I Freeimage
170 frees the resources used by its argument image.
171 .PP
172 .I Nameimage
173 publishes in the server the image
174 .I i
175 under the given
176 .IR name .
177 If
178 .I in
179 is non-zero, the image is published; otherwise
180 .I i
181 must be already named
182 .I name
183 and it is withdrawn from publication.
184 .I Namedimage
185 returns a reference to the image published under the given
186 .I name
187 on
188 .B Display
189 .IR d .
190 These routines permit unrelated applications sharing a display to share an image;
191 for example they provide the mechanism behind
192 .B getwindow
193 (see
194 .MR graphics (3) ).
195 .PP
196 The RGB values in a color are
197 .I premultiplied
198 by the alpha value; for example, a 50% red is
199 .B 0x7F00007F
200 not
201 .BR 0xFF00007F .
202 The function
203 .I setalpha
204 performs the alpha computation on a given
205 .BR color ,
206 ignoring its initial alpha value, multiplying the components by the supplied
207 .BR alpha .
208 For example, to make a 50% red color value, one could execute
209 .B setalpha(DRed,
210 .BR 0x7F) .
211 .PP
212 The remaining functions deal with moving groups of pixel
213 values between image and user space or external files.
214 There is a fixed format for the exchange and storage of
215 image data
216 (see
217 .MR image (7) ).
218 .PP
219 .I Unloadimage
220 reads a rectangle of pixels from image
221 .I i
222 into
223 .IR data ,
224 whose length is specified by
225 .IR ndata .
226 It is an error if
227 .I ndata
228 is too small to accommodate the pixels.
229 .PP
230 .I Loadimage
231 replaces the specified rectangle in image
232 .I i
233 with the
234 .I ndata
235 bytes of
236 .IR data .
237 .PP
238 The pixels are presented one horizontal line at a time,
239 starting with the top-left pixel of
240 .IR r .
241 In the data processed by these routines, each scan line starts with a new byte in the array,
242 leaving the last byte of the previous line partially empty, if necessary.
243 Pixels are packed as tightly as possible within
244 .IR data ,
245 regardless of the rectangle being extracted.
246 Bytes are filled from most to least significant bit order,
247 as the
248 .I x
249 coordinate increases, aligned so
250 .IR x =0
251 would appear as the leftmost pixel of its byte.
252 Thus, for
253 .B depth
254 1, the pixel at
255 .I x
256 offset 165 within the rectangle will be in a
257 .I data
258 byte at bit-position
259 .B 0x04
260 regardless of the overall
261 rectangle: 165 mod 8 equals 5, and
262 .B "0x80\ >>\ 5"
263 equals
264 .BR 0x04 .
265 .PP
266 .B Cloadimage
267 does the same as
268 .IR loadimage ,
269 but for
270 .I ndata
271 bytes of compressed image
272 .I data
273 (see
274 .MR image (7) ).
275 On each call to
276 .IR cloadimage,
277 the
278 .I data
279 must be at the beginning of a compressed data block, in particular,
280 it should start with the
281 .B y
282 coordinate and data length for the block.
283 .PP
284 .IR Loadimage ,
285 .IR cloadimage ,
286 and
287 .I unloadimage
288 return the number of bytes copied.
289 .PP
290 .I Readimage
291 creates an image from data contained in an external file (see
292 .MR image (7)
293 for the file format);
294 .I fd
295 is a file descriptor obtained by opening such a file for reading.
296 The returned image is allocated using
297 .IR allocimage .
298 The
299 .I dolock
300 flag specifies whether the
301 .B Display
302 should be synchronized for multithreaded access; single-threaded
303 programs can leave it zero.
304 .PP
305 .I Writeimage
306 writes image
307 .I i
308 onto file descriptor
309 .IR fd ,
310 which should be open for writing.
311 The format is as described for
312 .IR readimage .
313 .PP
314 .I Readimage
315 and
316 .I writeimage
317 do not close
318 .IR fd .
319 .PP
320 .I Bytesperline
321 and
322 .I wordsperline
323 return the number of bytes or words occupied in memory by one scan line of rectangle
324 .I r
325 in an image with
326 .I d
327 bits per pixel.
328 .SH EXAMPLE
329 To allocate a single-pixel replicated image that may be used to paint a region red,
330 .EX
331 red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);
332 .EE
333 .SH SOURCE
334 .B \*9/src/libdraw
335 .SH "SEE ALSO"
336 .MR graphics (3) ,
337 .MR draw (3) ,
338 .MR draw (3) ,
339 .MR image (7)
340 .SH DIAGNOSTICS
341 These functions return pointer 0 or integer \-1 on failure, usually due to insufficient
342 memory.
343 .PP
344 May set
345 .IR errstr .
346 .SH BUGS
347 .B Depth
348 must be a divisor or multiple of 8.