1 cfa37a7b 2004-04-10 devnull .TH DRAW 3
3 058b0118 2005-01-03 devnull Image, draw, drawop, gendraw, gendrawop, drawreplxy, drawrepl,
4 058b0118 2005-01-03 devnull replclipr, line, lineop, poly, polyop, fillpoly, fillpolyop, bezier, bezierop,
5 058b0118 2005-01-03 devnull bezspline, bezsplineop, bezsplinepts, fillbezier, fillbezierop,
6 058b0118 2005-01-03 devnull fillbezspline, fillbezsplineop, ellipse, ellipseop,
7 058b0118 2005-01-03 devnull fillellipse, fillellipseop, arc, arcop, fillarc, fillarcop,
8 41305b23 2008-12-03 jas icossin, icossin2, border, borderop, string, stringop, stringn, stringnop,
9 058b0118 2005-01-03 devnull runestring, runestringop, runestringn, runestringnop, stringbg,
10 058b0118 2005-01-03 devnull stringbgop, stringnbg, stringnbgop, runestringbg, runestringbgop,
11 058b0118 2005-01-03 devnull runestringnbg, runestringnbgop, _string, ARROW, drawsetdebug \- graphics functions
17 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
24 cfa37a7b 2004-04-10 devnull #include <u.h>
25 cfa37a7b 2004-04-10 devnull #include <libc.h>
26 cfa37a7b 2004-04-10 devnull #include <draw.h>
29 cfa37a7b 2004-04-10 devnull struct Image
31 cfa37a7b 2004-04-10 devnull Display *display; /* display holding data */
32 cfa37a7b 2004-04-10 devnull int id; /* id of system-held Image */
33 cfa37a7b 2004-04-10 devnull Rectangle r; /* rectangle in data area, local coords */
34 cfa37a7b 2004-04-10 devnull Rectangle clipr; /* clipping region */
35 cfa37a7b 2004-04-10 devnull ulong chan; /* pixel channel format descriptor */
36 cfa37a7b 2004-04-10 devnull int depth; /* number of bits per pixel */
37 cfa37a7b 2004-04-10 devnull int repl; /* flag: data replicates to tile clipr */
38 cfa37a7b 2004-04-10 devnull Screen *screen; /* 0 if not a window */
39 cfa37a7b 2004-04-10 devnull Image *next; /* next in list of windows */
42 cfa37a7b 2004-04-10 devnull typedef enum
44 cfa37a7b 2004-04-10 devnull /* Porter-Duff compositing operators */
45 cfa37a7b 2004-04-10 devnull Clear = 0,
47 cfa37a7b 2004-04-10 devnull SinD = 8,
48 cfa37a7b 2004-04-10 devnull DinS = 4,
49 cfa37a7b 2004-04-10 devnull SoutD = 2,
50 cfa37a7b 2004-04-10 devnull DoutS = 1,
52 cfa37a7b 2004-04-10 devnull S = SinD|SoutD,
53 cfa37a7b 2004-04-10 devnull SoverD = SinD|SoutD|DoutS,
54 cfa37a7b 2004-04-10 devnull SatopD = SinD|DoutS,
55 cfa37a7b 2004-04-10 devnull SxorD = SoutD|DoutS,
57 cfa37a7b 2004-04-10 devnull D = DinS|DoutS,
58 cfa37a7b 2004-04-10 devnull DoverS = DinS|DoutS|SoutD,
59 cfa37a7b 2004-04-10 devnull DatopS = DinS|SoutD,
60 cfa37a7b 2004-04-10 devnull DxorS = DoutS|SoutD, /* == SxorD */
62 cfa37a7b 2004-04-10 devnull Ncomp = 12,
63 cfa37a7b 2004-04-10 devnull } Drawop;
66 cfa37a7b 2004-04-10 devnull .ta +\w'\fL 'u +\w'\fL 'u +6n +4n
67 cfa37a7b 2004-04-10 devnull void draw(Image *dst, Rectangle r, Image *src,
68 cfa37a7b 2004-04-10 devnull Image *mask, Point p)
70 cfa37a7b 2004-04-10 devnull void drawop(Image *dst, Rectangle r, Image *src,
71 cfa37a7b 2004-04-10 devnull Image *mask, Point p, Drawop op)
73 cfa37a7b 2004-04-10 devnull void gendraw(Image *dst, Rectangle r, Image *src, Point sp,
74 cfa37a7b 2004-04-10 devnull Image *mask, Point mp)
76 cfa37a7b 2004-04-10 devnull void gendrawop(Image *dst, Rectangle r, Image *src, Point sp,
77 cfa37a7b 2004-04-10 devnull Image *mask, Point mp, Drawop op)
79 cfa37a7b 2004-04-10 devnull int drawreplxy(int min, int max, int x)
81 cfa37a7b 2004-04-10 devnull Point drawrepl(Rectangle r, Point p)
83 cfa37a7b 2004-04-10 devnull void replclipr(Image *i, int repl, Rectangle clipr)
85 cfa37a7b 2004-04-10 devnull void line(Image *dst, Point p0, Point p1, int end0, int end1,
86 cfa37a7b 2004-04-10 devnull int radius, Image *src, Point sp)
88 cfa37a7b 2004-04-10 devnull void lineop(Image *dst, Point p0, Point p1, int end0, int end1,
89 cfa37a7b 2004-04-10 devnull int radius, Image *src, Point sp, Drawop op)
91 cfa37a7b 2004-04-10 devnull void poly(Image *dst, Point *p, int np, int end0, int end1,
92 cfa37a7b 2004-04-10 devnull int radius, Image *src, Point sp)
94 cfa37a7b 2004-04-10 devnull void polyop(Image *dst, Point *p, int np, int end0, int end1,
95 cfa37a7b 2004-04-10 devnull int radius, Image *src, Point sp, Drawop op)
97 cfa37a7b 2004-04-10 devnull void fillpoly(Image *dst, Point *p, int np, int wind,
98 cfa37a7b 2004-04-10 devnull Image *src, Point sp)
100 cfa37a7b 2004-04-10 devnull void fillpolyop(Image *dst, Point *p, int np, int wind,
101 cfa37a7b 2004-04-10 devnull Image *src, Point sp, Drawop op)
103 cfa37a7b 2004-04-10 devnull int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
104 cfa37a7b 2004-04-10 devnull int end0, int end1, int radius, Image *src, Point sp)
106 cfa37a7b 2004-04-10 devnull int bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
107 cfa37a7b 2004-04-10 devnull int end0, int end1, int radius, Image *src, Point sp,
108 cfa37a7b 2004-04-10 devnull Drawop op)
110 cfa37a7b 2004-04-10 devnull int bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
111 cfa37a7b 2004-04-10 devnull int radius, Image *src, Point sp)
113 cfa37a7b 2004-04-10 devnull int bezsplineop(Image *dst, Point *pt, int npt, int end0, int end1,
114 cfa37a7b 2004-04-10 devnull int radius, Image *src, Point sp, Drawop op)
116 cfa37a7b 2004-04-10 devnull int bezsplinepts(Point *pt, int npt, Point **pp)
118 cfa37a7b 2004-04-10 devnull int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
119 cfa37a7b 2004-04-10 devnull int w, Image *src, Point sp)
121 cfa37a7b 2004-04-10 devnull int fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
122 cfa37a7b 2004-04-10 devnull int w, Image *src, Point sp, Drawop op)
124 cfa37a7b 2004-04-10 devnull int fillbezspline(Image *dst, Point *pt, int npt, int w,
125 cfa37a7b 2004-04-10 devnull Image *src, Point sp)
127 cfa37a7b 2004-04-10 devnull int fillbezsplineop(Image *dst, Point *pt, int npt, int w,
128 cfa37a7b 2004-04-10 devnull Image *src, Point sp, Drawop op)
130 cfa37a7b 2004-04-10 devnull void ellipse(Image *dst, Point c, int a, int b, int thick,
131 cfa37a7b 2004-04-10 devnull Image *src, Point sp)
133 cfa37a7b 2004-04-10 devnull void ellipseop(Image *dst, Point c, int a, int b, int thick,
134 cfa37a7b 2004-04-10 devnull Image *src, Point sp, Drawop op)
136 cfa37a7b 2004-04-10 devnull void fillellipse(Image *dst, Point c, int a, int b,
137 cfa37a7b 2004-04-10 devnull Image *src, Point sp)
139 cfa37a7b 2004-04-10 devnull void fillellipseop(Image *dst, Point c, int a, int b,
140 cfa37a7b 2004-04-10 devnull Image *src, Point sp, Drawop op)
142 cfa37a7b 2004-04-10 devnull void arc(Image *dst, Point c, int a, int b, int thick,
143 cfa37a7b 2004-04-10 devnull Image *src, Point sp, int alpha, int phi)
145 cfa37a7b 2004-04-10 devnull void arcop(Image *dst, Point c, int a, int b, int thick,
146 cfa37a7b 2004-04-10 devnull Image *src, Point sp, int alpha, int phi, Drawop op)
148 cfa37a7b 2004-04-10 devnull void fillarc(Image *dst, Point c, int a, int b, Image *src,
149 cfa37a7b 2004-04-10 devnull Point sp, int alpha, int phi)
151 cfa37a7b 2004-04-10 devnull void fillarcop(Image *dst, Point c, int a, int b, Image *src,
152 cfa37a7b 2004-04-10 devnull Point sp, int alpha, int phi, Drawop op)
154 cfa37a7b 2004-04-10 devnull int icossin(int deg, int *cosp, int *sinp)
156 cfa37a7b 2004-04-10 devnull int icossin2(int x, int y, int *cosp, int *sinp)
158 cfa37a7b 2004-04-10 devnull void border(Image *dst, Rectangle r, int i, Image *color, Point sp)
160 41305b23 2008-12-03 jas void borderop(Image *im, Rectangle r, int i, Image *color, Point sp,
164 cfa37a7b 2004-04-10 devnull Point string(Image *dst, Point p, Image *src, Point sp,
165 cfa37a7b 2004-04-10 devnull Font *f, char *s)
167 cfa37a7b 2004-04-10 devnull Point stringop(Image *dst, Point p, Image *src, Point sp,
168 cfa37a7b 2004-04-10 devnull Font *f, char *s, Drawop op)
170 cfa37a7b 2004-04-10 devnull Point stringn(Image *dst, Point p, Image *src, Point sp,
171 cfa37a7b 2004-04-10 devnull Font *f, char *s, int len)
173 cfa37a7b 2004-04-10 devnull Point stringnop(Image *dst, Point p, Image *src, Point sp,
174 cfa37a7b 2004-04-10 devnull Font *f, char *s, int len, Drawop op)
176 cfa37a7b 2004-04-10 devnull Point runestring(Image *dst, Point p, Image *src, Point sp,
177 cfa37a7b 2004-04-10 devnull Font *f, Rune *r)
179 cfa37a7b 2004-04-10 devnull Point runestringop(Image *dst, Point p, Image *src, Point sp,
180 cfa37a7b 2004-04-10 devnull Font *f, Rune *r, Drawop op)
182 cfa37a7b 2004-04-10 devnull Point runestringn(Image *dst, Point p, Image *src, Point sp,
183 cfa37a7b 2004-04-10 devnull Font *f, Rune *r, int len)
185 cfa37a7b 2004-04-10 devnull Point runestringnop(Image *dst, Point p, Image *src, Point sp,
186 cfa37a7b 2004-04-10 devnull Font *f, Rune *r, int len, Drawop op)
188 cfa37a7b 2004-04-10 devnull Point stringbg(Image *dst, Point p, Image *src, Point sp,
189 cfa37a7b 2004-04-10 devnull Font *f, char *s, Image *bg, Point bgp)
191 cfa37a7b 2004-04-10 devnull Point stringbgop(Image *dst, Point p, Image *src, Point sp,
192 cfa37a7b 2004-04-10 devnull Font *f, char *s, Image *bg, Point bgp, Drawop op)
194 cfa37a7b 2004-04-10 devnull Point stringnbg(Image *dst, Point p, Image *src, Point sp,
195 cfa37a7b 2004-04-10 devnull Font *f, char *s, int len, Image *bg, Point bgp)
197 cfa37a7b 2004-04-10 devnull Point stringnbgop(Image *dst, Point p, Image *src, Point sp,
198 cfa37a7b 2004-04-10 devnull Font *f, char *s, int len, Image *bg, Point bgp, Drawop op)
200 cfa37a7b 2004-04-10 devnull Point runestringbg(Image *dst, Point p, Image *src, Point sp,
201 cfa37a7b 2004-04-10 devnull Font *f, Rune *r, Image *bg, Point bgp)
203 cfa37a7b 2004-04-10 devnull Point runestringbgop(Image *dst, Point p, Image *src, Point sp,
204 cfa37a7b 2004-04-10 devnull Font *f, Rune *r, Image *bg, Point bgp, Drawop op)
206 cfa37a7b 2004-04-10 devnull Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
207 cfa37a7b 2004-04-10 devnull Font *f, Rune *r, int len, Image *bg, Point bgp)
209 cfa37a7b 2004-04-10 devnull Point runestringnbgop(Image *dst, Point p, Image *src, Point sp,
210 cfa37a7b 2004-04-10 devnull Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op)
212 cfa37a7b 2004-04-10 devnull Point _string(Image *dst, Point p, Image *src,
213 cfa37a7b 2004-04-10 devnull Point sp, Font *f, char *s, Rune *r, int len,
214 cfa37a7b 2004-04-10 devnull Rectangle clipr, Image *bg, Point bgp, Drawop op)
216 cfa37a7b 2004-04-10 devnull void drawsetdebug(int on)
221 cfa37a7b 2004-04-10 devnull /* line ends */
222 cfa37a7b 2004-04-10 devnull Endsquare = 0,
223 cfa37a7b 2004-04-10 devnull Enddisc = 1,
224 cfa37a7b 2004-04-10 devnull Endarrow = 2,
225 cfa37a7b 2004-04-10 devnull Endmask = 0x1F
228 cfa37a7b 2004-04-10 devnull #define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))
229 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
231 cfa37a7b 2004-04-10 devnull .B Image
232 cfa37a7b 2004-04-10 devnull type defines rectangular pictures and the methods to draw upon them;
233 cfa37a7b 2004-04-10 devnull it is also the building block for higher level objects such as
234 cfa37a7b 2004-04-10 devnull windows and fonts.
235 cfa37a7b 2004-04-10 devnull In particular, a window is represented as an
236 cfa37a7b 2004-04-10 devnull .BR Image ;
237 cfa37a7b 2004-04-10 devnull no special operators are needed to draw on a window.
241 cfa37a7b 2004-04-10 devnull The coordinates of the rectangle in the plane for which the
242 cfa37a7b 2004-04-10 devnull .B Image
243 cfa37a7b 2004-04-10 devnull has defined pixel values.
244 cfa37a7b 2004-04-10 devnull It should not be modified after the image is created.
246 cfa37a7b 2004-04-10 devnull .B clipr
247 cfa37a7b 2004-04-10 devnull The clipping rectangle: operations that read or write
248 cfa37a7b 2004-04-10 devnull the image will not access pixels outside
249 cfa37a7b 2004-04-10 devnull .BR clipr .
250 cfa37a7b 2004-04-10 devnull Frequently,
251 cfa37a7b 2004-04-10 devnull .B clipr
252 cfa37a7b 2004-04-10 devnull is the same as
254 cfa37a7b 2004-04-10 devnull but it may differ; see in particular the discussion of
255 cfa37a7b 2004-04-10 devnull .BR repl .
256 cfa37a7b 2004-04-10 devnull The clipping region may be modified dynamically using
257 cfa37a7b 2004-04-10 devnull .I replclipr
258 cfa37a7b 2004-04-10 devnull .RI ( q.v. ).
261 cfa37a7b 2004-04-10 devnull The pixel channel format descriptor, as described in
262 d32deab1 2020-08-16 rsc .MR image (7) .
263 cfa37a7b 2004-04-10 devnull The value should not be modified after the image is created.
265 cfa37a7b 2004-04-10 devnull .B depth
267 cfa37a7b 2004-04-10 devnull number of bits per pixel in the picture;
268 cfa37a7b 2004-04-10 devnull it is identically
269 cfa37a7b 2004-04-10 devnull .B chantodepth(chan)
271 d32deab1 2020-08-16 rsc .MR graphics (3) )
272 cfa37a7b 2004-04-10 devnull and is provided as a convenience.
273 cfa37a7b 2004-04-10 devnull The value should not be modified after the image is created.
276 cfa37a7b 2004-04-10 devnull A boolean value specifying whether the image is tiled to cover
277 cfa37a7b 2004-04-10 devnull the plane when used as a source for a drawing operation.
280 cfa37a7b 2004-04-10 devnull is zero, operations are restricted to the intersection of
283 cfa37a7b 2004-04-10 devnull .BR clipr .
288 cfa37a7b 2004-04-10 devnull defines the tile to be replicated and
289 cfa37a7b 2004-04-10 devnull .B clipr
290 cfa37a7b 2004-04-10 devnull defines the portion of the plane covered by the tiling, in other words,
292 cfa37a7b 2004-04-10 devnull is replicated to cover
293 cfa37a7b 2004-04-10 devnull .BR clipr ;
294 cfa37a7b 2004-04-10 devnull in such cases
297 cfa37a7b 2004-04-10 devnull .B clipr
298 cfa37a7b 2004-04-10 devnull are independent.
300 cfa37a7b 2004-04-10 devnull For example, a replicated image with
302 cfa37a7b 2004-04-10 devnull set to ((0,\ 0),\ (1,\ 1)) and
303 cfa37a7b 2004-04-10 devnull .B clipr
304 cfa37a7b 2004-04-10 devnull set to ((0,\ 0),\ (100,\ 100)),
305 cfa37a7b 2004-04-10 devnull with the single pixel of
307 cfa37a7b 2004-04-10 devnull set to blue,
308 cfa37a7b 2004-04-10 devnull behaves identically to an image with
311 cfa37a7b 2004-04-10 devnull .B clipr
312 cfa37a7b 2004-04-10 devnull both set to ((0,\ 0),\ (100,\ 100)) and all pixels set to blue.
313 cfa37a7b 2004-04-10 devnull However,
314 cfa37a7b 2004-04-10 devnull the first image requires far less memory.
315 cfa37a7b 2004-04-10 devnull The replication flag may be modified dynamically using
316 cfa37a7b 2004-04-10 devnull .I replclipr
317 cfa37a7b 2004-04-10 devnull .RI ( q.v. ).
319 cfa37a7b 2004-04-10 devnull Most of the drawing functions come in two forms:
320 cfa37a7b 2004-04-10 devnull a basic form, and an extended form that takes an extra
321 cfa37a7b 2004-04-10 devnull .B Drawop
322 cfa37a7b 2004-04-10 devnull to specify a Porter-Duff compositing operator to use.
323 cfa37a7b 2004-04-10 devnull The basic forms assume the operator is
324 cfa37a7b 2004-04-10 devnull .BR SoverD ,
325 cfa37a7b 2004-04-10 devnull which suffices for the vast majority of applications.
326 cfa37a7b 2004-04-10 devnull The extended forms are named by adding an
327 cfa37a7b 2004-04-10 devnull .RB - op
328 cfa37a7b 2004-04-10 devnull suffix to the basic form.
329 cfa37a7b 2004-04-10 devnull Only the basic forms are listed below.
331 cfa37a7b 2004-04-10 devnull .BI draw( dst\fP,\fP\ r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p )
333 cfa37a7b 2004-04-10 devnull is the standard drawing function.
334 cfa37a7b 2004-04-10 devnull Only those pixels within the intersection of
335 cfa37a7b 2004-04-10 devnull .IB dst ->r
337 cfa37a7b 2004-04-10 devnull .IB dst ->clipr
338 cfa37a7b 2004-04-10 devnull will be affected;
341 cfa37a7b 2004-04-10 devnull .IB dst ->repl\fR.
342 cfa37a7b 2004-04-10 devnull The operation proceeds as follows
343 cfa37a7b 2004-04-10 devnull (this is a description of the behavior, not the implementation):
348 cfa37a7b 2004-04-10 devnull is set in
351 cfa37a7b 2004-04-10 devnull .IR mask ,
352 cfa37a7b 2004-04-10 devnull replicate their contents to fill
353 cfa37a7b 2004-04-10 devnull their clip rectangles.
355 cfa37a7b 2004-04-10 devnull Translate
361 cfa37a7b 2004-04-10 devnull is aligned with
362 cfa37a7b 2004-04-10 devnull .IB r .min\fR.
366 cfa37a7b 2004-04-10 devnull to the intersection of
369 cfa37a7b 2004-04-10 devnull .IB dst ->r\fR.
371 cfa37a7b 2004-04-10 devnull Intersect
374 cfa37a7b 2004-04-10 devnull .IB src ->clipr\fR.
376 cfa37a7b 2004-04-10 devnull .IB src ->repl
377 cfa37a7b 2004-04-10 devnull is false, also intersect
380 cfa37a7b 2004-04-10 devnull .IB src ->r\fR.
382 cfa37a7b 2004-04-10 devnull Intersect
385 cfa37a7b 2004-04-10 devnull .IB mask ->clipr\fR.
387 cfa37a7b 2004-04-10 devnull .IB mask ->repl
388 cfa37a7b 2004-04-10 devnull is false, also intersect
391 cfa37a7b 2004-04-10 devnull .IB mask ->r\fR.
393 cfa37a7b 2004-04-10 devnull For each location in
395 cfa37a7b 2004-04-10 devnull combine the
397 cfa37a7b 2004-04-10 devnull pixel with the
399 cfa37a7b 2004-04-10 devnull pixel using the alpha value
400 cfa37a7b 2004-04-10 devnull corresponding to the
405 cfa37a7b 2004-04-10 devnull has an explicit alpha channel, the alpha value
406 cfa37a7b 2004-04-10 devnull corresponding to the
408 cfa37a7b 2004-04-10 devnull pixel is simply that pixel's alpha channel.
409 cfa37a7b 2004-04-10 devnull Otherwise, the alpha value is the NTSC greyscale equivalent
410 cfa37a7b 2004-04-10 devnull of the color value, with white meaning opaque and black transparent.
411 cfa37a7b 2004-04-10 devnull In terms of the Porter-Duff compositing algebra,
413 cfa37a7b 2004-04-10 devnull replaces the
415 cfa37a7b 2004-04-10 devnull pixels with
416 cfa37a7b 2004-04-10 devnull .RI ( src
418 cfa37a7b 2004-04-10 devnull .IR mask )
420 cfa37a7b 2004-04-10 devnull .IR dst .
421 cfa37a7b 2004-04-10 devnull (In the extended form,
422 cfa37a7b 2004-04-10 devnull ``over'' is replaced by
423 cfa37a7b 2004-04-10 devnull .IR op ).
426 cfa37a7b 2004-04-10 devnull The various
427 cfa37a7b 2004-04-10 devnull pixel channel formats
428 cfa37a7b 2004-04-10 devnull involved need not be identical.
429 cfa37a7b 2004-04-10 devnull If the channels involved are smaller than 8-bits, they will
430 cfa37a7b 2004-04-10 devnull be promoted before the calculation by replicating the extant bits;
431 cfa37a7b 2004-04-10 devnull after the calculation, they will be truncated to their proper sizes.
433 cfa37a7b 2004-04-10 devnull \f5gendraw(\f2dst\fP, \f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\f5)\fP
434 cfa37a7b 2004-04-10 devnull Similar to
436 cfa37a7b 2004-04-10 devnull except that
437 cfa37a7b 2004-04-10 devnull .I gendraw
438 cfa37a7b 2004-04-10 devnull aligns the source and mask differently:
440 cfa37a7b 2004-04-10 devnull is aligned so
442 cfa37a7b 2004-04-10 devnull corresponds to
443 cfa37a7b 2004-04-10 devnull .IB r .min
446 cfa37a7b 2004-04-10 devnull is aligned so
448 cfa37a7b 2004-04-10 devnull corresponds to
449 cfa37a7b 2004-04-10 devnull .IB r .min .
450 cfa37a7b 2004-04-10 devnull For most purposes with simple masks and source images,
452 cfa37a7b 2004-04-10 devnull is sufficient, but
453 cfa37a7b 2004-04-10 devnull .B gendraw
454 cfa37a7b 2004-04-10 devnull is the general operator and the one all other drawing primitives are built upon.
456 cfa37a7b 2004-04-10 devnull .BI drawreplxy( min , max , x\f5)
459 cfa37a7b 2004-04-10 devnull to be in the half-open interval [\fImin\fP, \fImax\fP) by adding
460 cfa37a7b 2004-04-10 devnull or subtracting a multiple of \fImax-min\fP.
462 cfa37a7b 2004-04-10 devnull .BI drawrepl( r , p )
463 cfa37a7b 2004-04-10 devnull Clips the point \fIp\fP to be within the rectangle \fIr\fP
464 cfa37a7b 2004-04-10 devnull by translating the point horizontally by an integer multiple of rectangle width
465 cfa37a7b 2004-04-10 devnull and vertically by the height.
467 cfa37a7b 2004-04-10 devnull .BI replclipr( i , repl , clipr\f5)
468 cfa37a7b 2004-04-10 devnull Because the image data is stored on the server, local modifications to the
469 cfa37a7b 2004-04-10 devnull .B Image
470 cfa37a7b 2004-04-10 devnull data structure itself will have no effect.
471 cfa37a7b 2004-04-10 devnull .I Repclipr
472 cfa37a7b 2004-04-10 devnull modifies the local
473 cfa37a7b 2004-04-10 devnull .B Image
474 cfa37a7b 2004-04-10 devnull data structure's
477 cfa37a7b 2004-04-10 devnull .B clipr
478 cfa37a7b 2004-04-10 devnull fields, and notifies the server of their modification.
480 cfa37a7b 2004-04-10 devnull \f5line(\f2dst\fP, \f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
482 cfa37a7b 2004-04-10 devnull draws in
484 cfa37a7b 2004-04-10 devnull a line of width
485 cfa37a7b 2004-04-10 devnull .RI 1+2* thick
486 cfa37a7b 2004-04-10 devnull pixels joining points
489 cfa37a7b 2004-04-10 devnull .IR p1 .
490 cfa37a7b 2004-04-10 devnull The line is drawn using pixels from the
492 cfa37a7b 2004-04-10 devnull image aligned so
494 cfa37a7b 2004-04-10 devnull in the source corresponds to
496 cfa37a7b 2004-04-10 devnull in the destination.
497 cfa37a7b 2004-04-10 devnull The line touches both
500 cfa37a7b 2004-04-10 devnull .IR p1 ,
505 cfa37a7b 2004-04-10 devnull specify how the ends of the line are drawn.
506 cfa37a7b 2004-04-10 devnull .B Endsquare
507 cfa37a7b 2004-04-10 devnull terminates the line perpendicularly to the direction of the line; a thick line with
508 cfa37a7b 2004-04-10 devnull .B Endsquare
509 cfa37a7b 2004-04-10 devnull on both ends will be a rectangle.
510 cfa37a7b 2004-04-10 devnull .B Enddisc
511 cfa37a7b 2004-04-10 devnull terminates the line by drawing a disc of diameter
512 cfa37a7b 2004-04-10 devnull .RI 1+2* thick
513 cfa37a7b 2004-04-10 devnull centered on the end point.
514 cfa37a7b 2004-04-10 devnull .B Endarrow
515 cfa37a7b 2004-04-10 devnull terminates the line with an arrowhead whose tip touches the endpoint.
517 cfa37a7b 2004-04-10 devnull The macro
518 cfa37a7b 2004-04-10 devnull .B ARROW
519 cfa37a7b 2004-04-10 devnull permits explicit control of the shape of the arrow.
520 cfa37a7b 2004-04-10 devnull If all three parameters are zero, it produces the default arrowhead,
521 cfa37a7b 2004-04-10 devnull otherwise,
523 cfa37a7b 2004-04-10 devnull sets the distance along line from end of the regular line to tip,
525 cfa37a7b 2004-04-10 devnull sets the distance along line from the barb to the tip,
528 cfa37a7b 2004-04-10 devnull sets the distance perpendicular to the line from edge of line to the tip of the barb,
529 cfa37a7b 2004-04-10 devnull all in pixels.
532 cfa37a7b 2004-04-10 devnull and the other geometrical operators are equivalent to calls to
533 cfa37a7b 2004-04-10 devnull .I gendraw
534 cfa37a7b 2004-04-10 devnull using a mask produced by the geometric procedure.
536 cfa37a7b 2004-04-10 devnull \f5poly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
538 cfa37a7b 2004-04-10 devnull draws a general polygon; it
539 cfa37a7b 2004-04-10 devnull is conceptually equivalent to a series of calls to
541 cfa37a7b 2004-04-10 devnull joining adjacent points in the
542 cfa37a7b 2004-04-10 devnull array of
543 cfa37a7b 2004-04-10 devnull .B Points
545 cfa37a7b 2004-04-10 devnull which has
547 cfa37a7b 2004-04-10 devnull elements.
548 cfa37a7b 2004-04-10 devnull The ends of the polygon are specified as in
549 cfa37a7b 2004-04-10 devnull .IR line ;
550 cfa37a7b 2004-04-10 devnull interior lines are terminated with
551 cfa37a7b 2004-04-10 devnull .B Enddisc
552 cfa37a7b 2004-04-10 devnull to make smooth joins.
553 cfa37a7b 2004-04-10 devnull The source is aligned so
555 cfa37a7b 2004-04-10 devnull corresponds to
556 cfa37a7b 2004-04-10 devnull .IB p [0]\f1.
558 cfa37a7b 2004-04-10 devnull \f5fillpoly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
559 cfa37a7b 2004-04-10 devnull .I Fillpoly
562 cfa37a7b 2004-04-10 devnull but fills in the resulting polygon rather than outlining it.
563 cfa37a7b 2004-04-10 devnull The source is aligned so
565 cfa37a7b 2004-04-10 devnull corresponds to
566 cfa37a7b 2004-04-10 devnull .IB p [0]\f1.
567 cfa37a7b 2004-04-10 devnull The winding rule parameter
569 cfa37a7b 2004-04-10 devnull resolves ambiguities about what to fill if the polygon is self-intersecting.
573 cfa37a7b 2004-04-10 devnull .BR ~0 ,
574 cfa37a7b 2004-04-10 devnull a pixel is inside the polygon if the polygon's winding number about the point
575 cfa37a7b 2004-04-10 devnull is non-zero.
580 cfa37a7b 2004-04-10 devnull a pixel is inside if the winding number is odd.
581 cfa37a7b 2004-04-10 devnull Complementary values (0 or ~1) cause outside pixels to be filled.
582 cfa37a7b 2004-04-10 devnull The meaning of other values is undefined.
583 cfa37a7b 2004-04-10 devnull The polygon is closed with a line if necessary.
585 cfa37a7b 2004-04-10 devnull \f5bezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
586 cfa37a7b 2004-04-10 devnull .I Bezier
587 cfa37a7b 2004-04-10 devnull draws the
588 cfa37a7b 2004-04-10 devnull cubic Bezier curve defined by
589 cfa37a7b 2004-04-10 devnull .B Points
595 cfa37a7b 2004-04-10 devnull The end styles are determined by
598 cfa37a7b 2004-04-10 devnull .IR end1 ;
599 cfa37a7b 2004-04-10 devnull the thickness of the curve is
600 cfa37a7b 2004-04-10 devnull .RI 1+2* thick .
601 cfa37a7b 2004-04-10 devnull The source is aligned so
605 cfa37a7b 2004-04-10 devnull corresponds to
608 cfa37a7b 2004-04-10 devnull .IR dst .
610 cfa37a7b 2004-04-10 devnull \f5bezspline(\f2dst\fP, \f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
611 cfa37a7b 2004-04-10 devnull .I Bezspline
612 cfa37a7b 2004-04-10 devnull takes the same arguments as
614 cfa37a7b 2004-04-10 devnull but draws a quadratic B-spline (despite its name) rather than a polygon.
615 cfa37a7b 2004-04-10 devnull If the first and last points in
617 cfa37a7b 2004-04-10 devnull are equal, the spline has periodic end conditions.
619 cfa37a7b 2004-04-10 devnull \f5bezsplinepts(\f2pt\fP, \f2npt\fP, \f2pp\fP)
620 cfa37a7b 2004-04-10 devnull .I Bezsplinepts
621 cfa37a7b 2004-04-10 devnull returns in
623 cfa37a7b 2004-04-10 devnull a list of points making up the open polygon that
624 cfa37a7b 2004-04-10 devnull .I bezspline
625 cfa37a7b 2004-04-10 devnull would draw.
626 cfa37a7b 2004-04-10 devnull The caller is responsible for freeing
627 cfa37a7b 2004-04-10 devnull .IR *pp .
629 cfa37a7b 2004-04-10 devnull \f5fillbezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
630 cfa37a7b 2004-04-10 devnull .I Fillbezier
632 cfa37a7b 2004-04-10 devnull .I bezier
634 cfa37a7b 2004-04-10 devnull .I fillpoly
636 cfa37a7b 2004-04-10 devnull .IR poly .
638 cfa37a7b 2004-04-10 devnull \f5fillbezspline(\f2dst\fP, \f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
639 cfa37a7b 2004-04-10 devnull .I Fillbezspline
641 cfa37a7b 2004-04-10 devnull .I fillpoly
642 cfa37a7b 2004-04-10 devnull but fills the quadratic B-spline rather than the polygon outlined by
644 cfa37a7b 2004-04-10 devnull The spline is closed with a line if necessary.
646 cfa37a7b 2004-04-10 devnull \f5ellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
647 cfa37a7b 2004-04-10 devnull .I Ellipse
648 cfa37a7b 2004-04-10 devnull draws in
650 cfa37a7b 2004-04-10 devnull an ellipse centered on
652 cfa37a7b 2004-04-10 devnull with horizontal and vertical semiaxes
656 cfa37a7b 2004-04-10 devnull The source is aligned so
660 cfa37a7b 2004-04-10 devnull corresponds to
663 cfa37a7b 2004-04-10 devnull .IR dst .
664 cfa37a7b 2004-04-10 devnull The ellipse is drawn with thickness
665 cfa37a7b 2004-04-10 devnull .RI 1+2* thick .
667 cfa37a7b 2004-04-10 devnull \f5fillellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP)
668 cfa37a7b 2004-04-10 devnull .I Fillellipse
670 cfa37a7b 2004-04-10 devnull .I ellipse
671 cfa37a7b 2004-04-10 devnull but fills the ellipse rather than outlining it.
673 cfa37a7b 2004-04-10 devnull \f5arc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
676 cfa37a7b 2004-04-10 devnull .IR ellipse ,
677 cfa37a7b 2004-04-10 devnull but draws only that portion of the ellipse starting at angle
678 cfa37a7b 2004-04-10 devnull .I alpha
679 cfa37a7b 2004-04-10 devnull and extending through an angle of
680 cfa37a7b 2004-04-10 devnull .IR phi .
681 cfa37a7b 2004-04-10 devnull The angles are measured in degrees counterclockwise from the positive
685 cfa37a7b 2004-04-10 devnull \f5fillarc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
686 cfa37a7b 2004-04-10 devnull .I Fillarc
688 cfa37a7b 2004-04-10 devnull .IR arc ,
689 cfa37a7b 2004-04-10 devnull but fills the sector with the source color.
691 cfa37a7b 2004-04-10 devnull \f5icossin(\f2deg\fP, \f2cosp\fP, \f2sinp\fP)
692 cfa37a7b 2004-04-10 devnull .I Icossin
693 cfa37a7b 2004-04-10 devnull stores in
694 cfa37a7b 2004-04-10 devnull .BI * cosp
696 cfa37a7b 2004-04-10 devnull .BI * sinp
697 cfa37a7b 2004-04-10 devnull scaled integers representing the cosine and sine of the angle
698 cfa37a7b 2004-04-10 devnull .IR deg ,
699 cfa37a7b 2004-04-10 devnull measured in integer degrees.
700 cfa37a7b 2004-04-10 devnull The values are scaled so cos(0) is 1024.
702 cfa37a7b 2004-04-10 devnull \f5icossin2(\f2x\fP, \f2y\fP, \f2cosp\fP, \f2sinp\fP)
703 cfa37a7b 2004-04-10 devnull .I Icossin2
704 cfa37a7b 2004-04-10 devnull is analogous to
705 cfa37a7b 2004-04-10 devnull .IR icossin,
706 cfa37a7b 2004-04-10 devnull with the angle represented not in degrees but implicitly by the point
707 cfa37a7b 2004-04-10 devnull .RI ( x , y ).
708 cfa37a7b 2004-04-10 devnull It is to
709 cfa37a7b 2004-04-10 devnull .I icossin
711 cfa37a7b 2004-04-10 devnull .B atan2
715 d32deab1 2020-08-16 rsc .MR sin (3) ).
717 cfa37a7b 2004-04-10 devnull .BI border( dst\fP,\fP\ r\fP,\fP\ i\fP,\fP\ color\fP,\fP\ sp\fP)
718 cfa37a7b 2004-04-10 devnull .I Border
719 cfa37a7b 2004-04-10 devnull draws an outline of rectangle
721 cfa37a7b 2004-04-10 devnull in the specified
722 cfa37a7b 2004-04-10 devnull .IR color .
723 cfa37a7b 2004-04-10 devnull The outline has width
725 cfa37a7b 2004-04-10 devnull if positive, the border goes inside the rectangle; negative, outside.
726 cfa37a7b 2004-04-10 devnull The source is aligned so
728 cfa37a7b 2004-04-10 devnull corresponds to
729 cfa37a7b 2004-04-10 devnull .IB r .min .
731 cfa37a7b 2004-04-10 devnull .BI string( dst\fP,\fP\ p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ s )
732 cfa37a7b 2004-04-10 devnull .I String
733 cfa37a7b 2004-04-10 devnull draws in
735 cfa37a7b 2004-04-10 devnull characters specified by the string
738 cfa37a7b 2004-04-10 devnull .IR font ;
739 cfa37a7b 2004-04-10 devnull it is equivalent to a series of calls to
740 cfa37a7b 2004-04-10 devnull .I gendraw
741 cfa37a7b 2004-04-10 devnull using source
743 cfa37a7b 2004-04-10 devnull and masks determined by the character shapes.
744 cfa37a7b 2004-04-10 devnull The text is positioned with the left of the first character at
745 cfa37a7b 2004-04-10 devnull .IB p .x
746 cfa37a7b 2004-04-10 devnull and the top of the line of text at
747 cfa37a7b 2004-04-10 devnull .IB p .y\f1.
748 cfa37a7b 2004-04-10 devnull The source is positioned so
752 cfa37a7b 2004-04-10 devnull corresponds to
755 cfa37a7b 2004-04-10 devnull .IR dst .
756 cfa37a7b 2004-04-10 devnull .I String
757 cfa37a7b 2004-04-10 devnull returns a
758 cfa37a7b 2004-04-10 devnull .B Point
759 cfa37a7b 2004-04-10 devnull that is the position of the next character that would be drawn if the string were longer.
761 cfa37a7b 2004-04-10 devnull For characters with undefined
762 cfa37a7b 2004-04-10 devnull or zero-width images in the font, the character at font position 0 (NUL) is drawn.
764 cfa37a7b 2004-04-10 devnull The other string routines are variants of this basic form, and
765 cfa37a7b 2004-04-10 devnull have names that encode their variant behavior.
766 cfa37a7b 2004-04-10 devnull Routines whose names contain
768 cfa37a7b 2004-04-10 devnull accept a string of Runes rather than
769 cfa37a7b 2004-04-10 devnull .SM UTF\c
770 cfa37a7b 2004-04-10 devnull -encoded bytes.
771 cfa37a7b 2004-04-10 devnull Routines ending in
773 cfa37a7b 2004-04-10 devnull accept an argument,
775 cfa37a7b 2004-04-10 devnull that defines the number of characters to draw rather than accepting a NUL-terminated
777 cfa37a7b 2004-04-10 devnull Routines containing
779 cfa37a7b 2004-04-10 devnull draw the background behind the characters in the specified color
780 cfa37a7b 2004-04-10 devnull .RI ( bg )
782 cfa37a7b 2004-04-10 devnull alignment
783 cfa37a7b 2004-04-10 devnull .RI ( bgp );
784 cfa37a7b 2004-04-10 devnull normally the text is drawn leaving the background intact.
786 cfa37a7b 2004-04-10 devnull The routine
787 cfa37a7b 2004-04-10 devnull .I _string
788 cfa37a7b 2004-04-10 devnull captures all this behavior into a single operator. Whether it draws a
791 cfa37a7b 2004-04-10 devnull or Rune string depends on whether
795 cfa37a7b 2004-04-10 devnull is null (the string length is always determined by
796 cfa37a7b 2004-04-10 devnull .IR len ).
799 cfa37a7b 2004-04-10 devnull is non-null, it is used as a background color.
801 cfa37a7b 2004-04-10 devnull .I clipr
802 cfa37a7b 2004-04-10 devnull argument allows further management of clipping when drawing the string;
803 cfa37a7b 2004-04-10 devnull it is intersected with the usual clipping rectangles to further limit the extent of the text.
805 cfa37a7b 2004-04-10 devnull .BI drawsetdebug( on )
806 cfa37a7b 2004-04-10 devnull Turns on or off debugging output (usually
807 cfa37a7b 2004-04-10 devnull to a serial line) according to whether
809 cfa37a7b 2004-04-10 devnull is non-zero.
810 cfa37a7b 2004-04-10 devnull .SH SOURCE
811 c3674de4 2005-01-11 devnull .B \*9/src/libdraw
812 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
813 d32deab1 2020-08-16 rsc .MR graphics (3) ,
814 d32deab1 2020-08-16 rsc .MR stringsize (3) ,
815 d32deab1 2020-08-16 rsc .MR color (7) ,
816 d32deab1 2020-08-16 rsc .MR utf (7) ,
817 d32deab1 2020-08-16 rsc .MR addpt (3)
819 cfa37a7b 2004-04-10 devnull T. Porter, T. Duff.
820 cfa37a7b 2004-04-10 devnull ``Compositing Digital Images'',
821 cfa37a7b 2004-04-10 devnull .I "Computer Graphics
822 cfa37a7b 2004-04-10 devnull (Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.
823 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
824 cfa37a7b 2004-04-10 devnull These routines call the graphics error function on fatal errors.
825 cfa37a7b 2004-04-10 devnull .SH BUGS
826 cfa37a7b 2004-04-10 devnull Anti-aliased characters can be drawn by defining a font
827 cfa37a7b 2004-04-10 devnull with multiple bits per pixel, but there are
828 cfa37a7b 2004-04-10 devnull no anti-aliasing geometric primitives.
