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