tmemdraw.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tmemdraw.3 (10090B)
---
1 .TH MEMDRAW 3
2 .SH NAME
3 Memimage,
4 Memdata,
5 Memdrawparam,
6 memimageinit,
7 wordaddr,
8 byteaddr,
9 memimagemove,
10 allocmemimage,
11 allocmemimaged,
12 readmemimage,
13 creadmemimage,
14 writememimage,
15 freememimage,
16 memsetchan,
17 loadmemimage,
18 cloadmemimage,
19 unloadmemimage,
20 memfillcolor,
21 memarc,
22 mempoly,
23 memellipse,
24 memfillpoly,
25 memimageline,
26 memimagedraw,
27 drawclip,
28 memlinebbox,
29 memlineendsize,
30 allocmemsubfont,
31 openmemsubfont,
32 freememsubfont,
33 memsubfontwidth,
34 getmemdefont,
35 memimagestring,
36 iprint,
37 hwdraw \- drawing routines for memory-resident images
38 .SH SYNOPSIS
39 .nf
40 .B #include <u.h>
41 .nf
42 .B #include <u.h>
43 .B #include <libc.h>
44 .B #include <draw.h>
45 .B #include <memdraw.h>
46 .PP
47 .ft L
48 typedef struct Memdata
49 {
50 ulong *base; /* allocated data pointer */
51 uchar *bdata; /* first byte of actual data; word-aligned */
52 int ref; /* number of Memimages using this data */
53 void* imref; /* last image that pointed at this */
54 int allocd; /* is this malloc'd? */
55 } Memdata;
56
57 enum {
58 Frepl = 1<<0, /* is replicated */
59 Fsimple = 1<<1, /* is 1x1 */
60 Fgrey = 1<<2, /* is grey */
61 Falpha = 1<<3, /* has explicit alpha */
62 Fcmap = 1<<4, /* has cmap channel */
63 Fbytes = 1<<5, /* has only 8-bit channels */
64 };
65
66 typedef struct Memimage
67 {
68 Rectangle r; /* rectangle in data area, local coords */
69 Rectangle clipr; /* clipping region */
70 int depth; /* number of bits of storage per pixel */
71 int nchan; /* number of channels */
72 ulong chan; /* channel descriptions */
73
74 Memdata *data; /* pointer to data */
75 int zero; /* data->bdata+zero==&byte containing (0,0) */
76 ulong width; /* width in words of a single scan line */
77 Memlayer *layer; /* nil if not a layer*/
78 ulong flags;
79 \fI...\fP
80 } Memimage;
81
82 typedef struct Memdrawparam
83 {
84 Memimage *dst;
85 Rectangle r;
86 Memimage *src;
87 Rectangle sr;
88 Memimage *mask;
89 Rectangle mr;
90 \fI...\fP
91 } Memdrawparam;
92
93 .ta \w'\fLMemsubfont* 'u
94 int drawdebug;
95 .ft
96 .PP
97 .ft L
98 .nf
99 void memimageinit(void)
100 ulong* wordaddr(Memimage *i, Point p)
101 uchar* byteaddr(Memimage *i, Point p)
102 void memimagemove(void *from, void *to)
103 .PP
104 .ft L
105 .nf
106 Memimage* allocmemimage(Rectangle r, ulong chan)
107 Memimage* allocmemimaged(Rectangle r, ulong chan, Memdata *data)
108 Memimage* readmemimage(int fd)
109 Memimage* creadmemimage(int fd)
110 int writememimage(int fd, Memimage *i)
111 void freememimage(Memimage *i)
112 int memsetchan(Memimage*, ulong)
113 .PP
114 .ft L
115 .nf
116 int loadmemimage(Memimage *i, Rectangle r,
117 uchar *buf, int nbuf)
118 int cloadmemimage(Memimage *i, Rectangle r,
119 uchar *buf, int nbuf)
120 int unloadmemimage(Memimage *i, Rectangle r,
121 uchar *buf, int nbuf)
122 void memfillcolor(Memimage *i, ulong color)
123 .PP
124 .ft L
125 .nf
126 void memarc(Memimage *dst, Point c, int a, int b, int thick,
127 Memimage *src, Point sp, int alpha, int phi, Drawop op)
128 void mempoly(Memimage *dst, Point *p, int np, int end0,
129 int end1, int radius, Memimage *src, Point sp, Drawop op)
130 void memellipse(Memimage *dst, Point c, int a, int b,
131 int thick, Memimage *src, Point sp, Drawop op)
132 void memfillpoly(Memimage *dst, Point *p, int np, int wind,
133 Memimage *src, Point sp, Drawop op)
134 void memimageline(Memimage *dst, Point p0, Point p1, int end0,
135 int end1, int radius, Memimage *src, Point sp, Drawop op)
136 void memimagedraw(Memimage *dst, Rectangle r, Memimage *src,
137 Point sp, Memimage *mask, Point mp, Drawop op)
138 .PP
139 .ft L
140 .nf
141 int drawclip(Memimage *dst, Rectangle *dr, Memimage *src,
142 Point *sp, Memimage *mask, Point *mp,
143 Rectangle *sr, Rectangle *mr)
144 Rectangle memlinebbox(Point p0, Point p1, int end0, int end1,
145 int radius)
146 int memlineendsize(int end)
147 .PP
148 .ft L
149 .nf
150 Memsubfont* allocmemsubfont(char *name, int n, int height,
151 int ascent, Fontchar *info, Memimage *i)
152 Memsubfont* openmemsubfont(char *name)
153 void freememsubfont(Memsubfont *f)
154 Point memsubfontwidth(Memsubfont *f, char *s)
155 Point memimagestring(Memimage *dst, Point p, Memimage *color,
156 Point cp, Memsubfont *f, char *cs, Drawop op)
157 .PP
158 .ft L
159 .nf
160 int iprint(char *fmt, ...)
161 int hwdraw(Memdrawparam *param)
162 .ft R
163 .SH DESCRIPTION
164 The
165 .B Memimage
166 type defines memory-resident rectangular pictures and the methods to draw upon them;
167 .BR Memimage s
168 differ from
169 .BR Image s
170 (see
171 .MR draw (3) )
172 in that they are manipulated directly in user memory rather than by
173 RPCs to the
174 .B /dev/draw
175 hierarchy.
176 The
177 .Bmemdraw
178 library is the basis for the kernel
179 .MR draw (3)
180 driver and also used by a number of programs that must manipulate
181 images without a display.
182 .PP
183 The
184 .BR r,
185 .BR clipr ,
186 .BR depth ,
187 .BR nchan ,
188 and
189 .BR chan
190 structure elements are identical to
191 the ones of the same name
192 in the
193 .B Image
194 structure.
195 .PP
196 The
197 .B flags
198 element of the
199 .B Memimage
200 structure holds a number of bits of information about the image.
201 In particular, it subsumes the
202 purpose of the
203 .B repl
204 element of
205 .B Image
206 structures.
207 .PP
208 .I Memimageinit
209 initializes various static data that the library depends on,
210 as well as the replicated solid color images
211 .BR memopaque ,
212 .BR memtransparent ,
213 .BR memblack ,
214 and
215 .BR memwhite .
216 It should be called before referring to any of these images
217 and before calling any of the other library functions.
218 .PP
219 Each
220 .B Memimage
221 points at a
222 .B Memdata
223 structure that in turn points at the actual pixel data for the image.
224 This allows multiple images to be associated with the same
225 .BR Memdata .
226 The first word of the data pointed at by
227 the
228 .B base
229 element of
230 .B Memdata
231 points back at the
232 .B Memdata
233 structure, so that in the Plan 9 kernel, the
234 memory allocator (see
235 Plan 9's
236 .IR pool (3))
237 can compact image memory
238 using
239 .IR memimagemove .
240 .PP
241 Because images can have different coordinate systems,
242 the
243 .B zero
244 element of the
245 .B Memimage
246 structure contains the offset that must be added
247 to the
248 .B bdata
249 element of the corresponding
250 .B Memdata
251 structure in order to yield a pointer to the data for the pixel (0,0).
252 Adding
253 .BR width
254 machine words
255 to this pointer moves it down one scan line.
256 The
257 .B depth
258 element can be used to determine how to move the
259 pointer horizontally.
260 Note that this method works even for images whose rectangles
261 do not include the origin, although one should only dereference
262 pointers corresponding to pixels within the image rectangle.
263 .I Wordaddr
264 and
265 .IR byteaddr
266 perform these calculations,
267 returning pointers to the word and byte, respectively,
268 that contain the beginning of the data for a given pixel.
269 .PP
270 .I Allocmemimage
271 allocates
272 images with a given rectangle and channel descriptor
273 (see
274 .B strtochan
275 in
276 .MR graphics (3) ),
277 creating a fresh
278 .B Memdata
279 structure and associated storage.
280 .I Allocmemimaged
281 is similar but uses the supplied
282 .I Memdata
283 structure rather than a new one.
284 The
285 .I readmemimage
286 function reads an uncompressed bitmap
287 from the given file descriptor,
288 while
289 .I creadmemimage
290 reads a compressed bitmap.
291 .I Writememimage
292 writes a compressed representation of
293 .I i
294 to file descriptor
295 .IR fd .
296 For more on bitmap formats, see
297 .MR image (7) .
298 .I Freememimage
299 frees images returned by any of these routines.
300 The
301 .B Memimage
302 structure contains some tables that are used
303 to store precomputed values depending on the channel descriptor.
304 .I Memsetchan
305 updates the
306 .B chan
307 element of the structure as well as these tables,
308 returning \-1 if passed a bad channel descriptor.
309 .PP
310 .I Loadmemimage
311 and
312 .I cloadmemimage
313 replace the pixel data for a given rectangle of an image
314 with the given buffer of uncompressed or compressed
315 data, respectively.
316 When calling
317 .IR cloadmemimage ,
318 the buffer must contain an
319 integral number of
320 compressed chunks of data that exactly cover the rectangle.
321 .I Unloadmemimage
322 retrieves the uncompressed pixel data for a given rectangle of an image.
323 All three return the number of bytes consumed on success,
324 and \-1 in case of an error.
325 .PP
326 .I Memfillcolor
327 fills an image with the given color, a 32-bit number as
328 described in
329 .MR color (3) .
330 .PP
331 .IR Memarc ,
332 .IR mempoly ,
333 .IR memellipse ,
334 .IR memfillpoly ,
335 .IR memimageline ,
336 and
337 .I memimagedraw
338 are identical to the
339 .IR arc ,
340 .IR poly ,
341 .IR ellipse ,
342 .IR fillpoly ,
343 .IR line ,
344 and
345 .IR gendraw ,
346 routines described in
347 .MR draw (3) ,
348 except that they operate on
349 .BR Memimage s
350 rather than
351 .BR Image s.
352 Similarly,
353 .IR allocmemsubfont ,
354 .IR openmemsubfont ,
355 .IR freememsubfont ,
356 .IR memsubfontwidth ,
357 and
358 .I memimagestring
359 are the
360 .B Memimage
361 analogues of
362 .IR allocsubfont ,
363 .IR openfont ,
364 .IR freesubfont ,
365 .IR strsubfontwidth ,
366 and
367 .B string
368 (see
369 .MR subfont (3)
370 and
371 .MR graphics (3) ),
372 except that they operate
373 only on
374 .BR Memsubfont s
375 rather than
376 .BR Font s.
377 .PP
378 .I Drawclip
379 takes the images involved in a draw operation,
380 together with the destination rectangle
381 .B dr
382 and source
383 and mask alignment points
384 .B sp
385 and
386 .BR mp ,
387 and
388 clips them according to the clipping rectangles of the images involved.
389 It also fills in the rectangles
390 .B sr
391 and
392 .B mr
393 with rectangles congruent to the returned destination rectangle
394 but translated so the upper left corners are the returned
395 .B sp
396 and
397 .BR mp .
398 .I Drawclip
399 returns zero when the clipped rectangle is empty.
400 .I Memlinebbox
401 returns a conservative bounding box containing a line between
402 two points
403 with given end styles
404 and radius.
405 .I Memlineendsize
406 calculates the extra length added to a line by attaching
407 an end of a given style.
408 .PP
409 The
410 .I hwdraw
411 and
412 .I iprint
413 functions are no-op stubs that may be overridden by clients
414 of the library.
415 .I Hwdraw
416 is called at each call to
417 .I memimagedraw
418 with the current request's parameters.
419 If it can satisfy the request, it should do so
420 and return 1.
421 If it cannot satisfy the request, it should return 0.
422 This allows (for instance) the kernel to take advantage
423 of hardware acceleration.
424 .I Iprint
425 should format and print its arguments;
426 it is given much debugging output when
427 the global integer variable
428 .B drawdebug
429 is non-zero.
430 In the kernel,
431 .I iprint
432 prints to a serial line rather than the screen, for obvious reasons.
433 .SH SOURCE
434 .B \*9/src/libmemdraw
435 .SH SEE ALSO
436 .MR addpt (3) ,
437 .MR color (3) ,
438 .MR draw (3) ,
439 .MR graphics (3) ,
440 .MR memlayer (3) ,
441 .MR stringsize (3) ,
442 .MR subfont (3) ,
443 .MR color (7) ,
444 .MR utf (7)
445 .SH BUGS
446 .I Memimagestring
447 is unusual in using a subfont rather than a font,
448 and in having no parameter to align the source.