3 Image, draw, gendraw, drawreplxy, drawrepl,
4 replclipr, line, poly, fillpoly, bezier, bezspline, fillbezier, fillbezspline, ellipse,
5 fillellipse, arc, fillarc, icossin, icossin2, border, string, stringn,
6 runestring, runestringn, stringbg, stringnbg, runestringbg,
7 runestringnbg, _string, ARROW, drawsetdebug \- graphics functions
27 Display *display; /* display holding data */
28 int id; /* id of system-held Image */
29 Rectangle r; /* rectangle in data area, local coords */
30 Rectangle clipr; /* clipping region */
31 ulong chan; /* pixel channel format descriptor */
32 int depth; /* number of bits per pixel */
33 int repl; /* flag: data replicates to tile clipr */
34 Screen *screen; /* 0 if not a window */
35 Image *next; /* next in list of windows */
40 /* Porter-Duff compositing operators */
49 SoverD = SinD|SoutD|DoutS,
54 DoverS = DinS|DoutS|SoutD,
56 DxorS = DoutS|SoutD, /* == SxorD */
62 .ta +\w'\fL 'u +\w'\fL 'u +6n +4n
63 void draw(Image *dst, Rectangle r, Image *src,
66 void drawop(Image *dst, Rectangle r, Image *src,
67 Image *mask, Point p, Drawop op)
69 void gendraw(Image *dst, Rectangle r, Image *src, Point sp,
70 Image *mask, Point mp)
72 void gendrawop(Image *dst, Rectangle r, Image *src, Point sp,
73 Image *mask, Point mp, Drawop op)
75 int drawreplxy(int min, int max, int x)
77 Point drawrepl(Rectangle r, Point p)
79 void replclipr(Image *i, int repl, Rectangle clipr)
81 void line(Image *dst, Point p0, Point p1, int end0, int end1,
82 int radius, Image *src, Point sp)
84 void lineop(Image *dst, Point p0, Point p1, int end0, int end1,
85 int radius, Image *src, Point sp, Drawop op)
87 void poly(Image *dst, Point *p, int np, int end0, int end1,
88 int radius, Image *src, Point sp)
90 void polyop(Image *dst, Point *p, int np, int end0, int end1,
91 int radius, Image *src, Point sp, Drawop op)
93 void fillpoly(Image *dst, Point *p, int np, int wind,
96 void fillpolyop(Image *dst, Point *p, int np, int wind,
97 Image *src, Point sp, Drawop op)
99 int bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
100 int end0, int end1, int radius, Image *src, Point sp)
102 int bezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
103 int end0, int end1, int radius, Image *src, Point sp,
106 int bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
107 int radius, Image *src, Point sp)
109 int bezsplineop(Image *dst, Point *pt, int npt, int end0, int end1,
110 int radius, Image *src, Point sp, Drawop op)
112 int bezsplinepts(Point *pt, int npt, Point **pp)
114 int fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
115 int w, Image *src, Point sp)
117 int fillbezierop(Image *dst, Point p0, Point p1, Point p2, Point p3,
118 int w, Image *src, Point sp, Drawop op)
120 int fillbezspline(Image *dst, Point *pt, int npt, int w,
121 Image *src, Point sp)
123 int fillbezsplineop(Image *dst, Point *pt, int npt, int w,
124 Image *src, Point sp, Drawop op)
126 void ellipse(Image *dst, Point c, int a, int b, int thick,
127 Image *src, Point sp)
129 void ellipseop(Image *dst, Point c, int a, int b, int thick,
130 Image *src, Point sp, Drawop op)
132 void fillellipse(Image *dst, Point c, int a, int b,
133 Image *src, Point sp)
135 void fillellipseop(Image *dst, Point c, int a, int b,
136 Image *src, Point sp, Drawop op)
138 void arc(Image *dst, Point c, int a, int b, int thick,
139 Image *src, Point sp, int alpha, int phi)
141 void arcop(Image *dst, Point c, int a, int b, int thick,
142 Image *src, Point sp, int alpha, int phi, Drawop op)
144 void fillarc(Image *dst, Point c, int a, int b, Image *src,
145 Point sp, int alpha, int phi)
147 void fillarcop(Image *dst, Point c, int a, int b, Image *src,
148 Point sp, int alpha, int phi, Drawop op)
150 int icossin(int deg, int *cosp, int *sinp)
152 int icossin2(int x, int y, int *cosp, int *sinp)
154 void border(Image *dst, Rectangle r, int i, Image *color, Point sp)
157 Point string(Image *dst, Point p, Image *src, Point sp,
160 Point stringop(Image *dst, Point p, Image *src, Point sp,
161 Font *f, char *s, Drawop op)
163 Point stringn(Image *dst, Point p, Image *src, Point sp,
164 Font *f, char *s, int len)
166 Point stringnop(Image *dst, Point p, Image *src, Point sp,
167 Font *f, char *s, int len, Drawop op)
169 Point runestring(Image *dst, Point p, Image *src, Point sp,
172 Point runestringop(Image *dst, Point p, Image *src, Point sp,
173 Font *f, Rune *r, Drawop op)
175 Point runestringn(Image *dst, Point p, Image *src, Point sp,
176 Font *f, Rune *r, int len)
178 Point runestringnop(Image *dst, Point p, Image *src, Point sp,
179 Font *f, Rune *r, int len, Drawop op)
181 Point stringbg(Image *dst, Point p, Image *src, Point sp,
182 Font *f, char *s, Image *bg, Point bgp)
184 Point stringbgop(Image *dst, Point p, Image *src, Point sp,
185 Font *f, char *s, Image *bg, Point bgp, Drawop op)
187 Point stringnbg(Image *dst, Point p, Image *src, Point sp,
188 Font *f, char *s, int len, Image *bg, Point bgp)
190 Point stringnbgop(Image *dst, Point p, Image *src, Point sp,
191 Font *f, char *s, int len, Image *bg, Point bgp, Drawop op)
193 Point runestringbg(Image *dst, Point p, Image *src, Point sp,
194 Font *f, Rune *r, Image *bg, Point bgp)
196 Point runestringbgop(Image *dst, Point p, Image *src, Point sp,
197 Font *f, Rune *r, Image *bg, Point bgp, Drawop op)
199 Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
200 Font *f, Rune *r, int len, Image *bg, Point bgp)
202 Point runestringnbgop(Image *dst, Point p, Image *src, Point sp,
203 Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op)
205 Point _string(Image *dst, Point p, Image *src,
206 Point sp, Font *f, char *s, Rune *r, int len,
207 Rectangle clipr, Image *bg, Point bgp, Drawop op)
209 void drawsetdebug(int on)
221 #define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))
225 type defines rectangular pictures and the methods to draw upon them;
226 it is also the building block for higher level objects such as
228 In particular, a window is represented as an
230 no special operators are needed to draw on a window.
234 The coordinates of the rectangle in the plane for which the
236 has defined pixel values.
237 It should not be modified after the image is created.
240 The clipping rectangle: operations that read or write
241 the image will not access pixels outside
247 but it may differ; see in particular the discussion of
249 The clipping region may be modified dynamically using
254 The pixel channel format descriptor, as described in
256 The value should not be modified after the image is created.
260 number of bits per pixel in the picture;
265 and is provided as a convenience.
266 The value should not be modified after the image is created.
269 A boolean value specifying whether the image is tiled to cover
270 the plane when used as a source for a drawing operation.
273 is zero, operations are restricted to the intersection of
281 defines the tile to be replicated and
283 defines the portion of the plane covered by the tiling, in other words,
285 is replicated to cover
293 For example, a replicated image with
295 set to ((0,\ 0),\ (1,\ 1)) and
297 set to ((0,\ 0),\ (100,\ 100)),
298 with the single pixel of
301 behaves identically to an image with
305 both set to ((0,\ 0),\ (100,\ 100)) and all pixels set to blue.
307 the first image requires far less memory.
308 The replication flag may be modified dynamically using
312 Most of the drawing functions come in two forms:
313 a basic form, and an extended form that takes an extra
315 to specify a Porter-Duff compositing operator to use.
316 The basic forms assume the operator is
318 which suffices for the vast majority of applications.
319 The extended forms are named by adding an
321 suffix to the basic form.
322 Only the basic forms are listed below.
324 .BI draw( dst\fP,\fP\ r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p )
326 is the standard drawing function.
327 Only those pixels within the intersection of
335 The operation proceeds as follows
336 (this is a description of the behavior, not the implementation):
345 replicate their contents to fill
346 their clip rectangles.
359 to the intersection of
370 is false, also intersect
381 is false, also intersect
392 pixel using the alpha value
398 has an explicit alpha channel, the alpha value
401 pixel is simply that pixel's alpha channel.
402 Otherwise, the alpha value is the NTSC greyscale equivalent
403 of the color value, with white meaning opaque and black transparent.
404 In terms of the Porter-Duff compositing algebra,
414 (In the extended form,
415 ``over'' is replaced by
420 pixel channel formats
421 involved need not be identical.
422 If the channels involved are smaller than 8-bits, they will
423 be promoted before the calculation by replicating the extant bits;
424 after the calculation, they will be truncated to their proper sizes.
426 \f5gendraw(\f2dst\fP, \f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\f5)\fP
431 aligns the source and mask differently:
443 For most purposes with simple masks and source images,
447 is the general operator and the one all other drawing primitives are built upon.
449 .BI drawreplxy( min , max , x\f5)
452 to be in the half-open interval [\fImin\fP, \fImax\fP) by adding
453 or subtracting a multiple of \fImax-min\fP.
455 .BI drawrepl( r , p )
456 Clips the point \fIp\fP to be within the rectangle \fIr\fP
457 by translating the point horizontally by an integer multiple of rectangle width
458 and vertically by the height.
460 .BI replclipr( i , repl , clipr\f5)
461 Because the image data is stored on the server, local modifications to the
463 data structure itself will have no effect.
471 fields, and notifies the server of their modification.
473 \f5line(\f2dst\fP, \f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
479 pixels joining points
483 The line is drawn using pixels from the
487 in the source corresponds to
490 The line touches both
498 specify how the ends of the line are drawn.
500 terminates the line perpendicularly to the direction of the line; a thick line with
502 on both ends will be a rectangle.
504 terminates the line by drawing a disc of diameter
506 centered on the end point.
508 terminates the line with an arrowhead whose tip touches the endpoint.
512 permits explicit control of the shape of the arrow.
513 If all three parameters are zero, it produces the default arrowhead,
516 sets the distance along line from end of the regular line to tip,
518 sets the distance along line from the barb to the tip,
521 sets the distance perpendicular to the line from edge of line to the tip of the barb,
525 and the other geometrical operators are equivalent to calls to
527 using a mask produced by the geometric procedure.
529 \f5poly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
531 draws a general polygon; it
532 is conceptually equivalent to a series of calls to
534 joining adjacent points in the
541 The ends of the polygon are specified as in
543 interior lines are terminated with
545 to make smooth joins.
546 The source is aligned so
551 \f5fillpoly(\f2dst\fP, \f2p\fP, \f2np\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
555 but fills in the resulting polygon rather than outlining it.
556 The source is aligned so
560 The winding rule parameter
562 resolves ambiguities about what to fill if the polygon is self-intersecting.
567 a pixel is inside the polygon if the polygon's winding number about the point
573 a pixel is inside if the winding number is odd.
574 Complementary values (0 or ~1) cause outside pixels to be filled.
575 The meaning of other values is undefined.
576 The polygon is closed with a line if necessary.
578 \f5bezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
581 cubic Bezier curve defined by
588 The end styles are determined by
592 the thickness of the curve is
594 The source is aligned so
603 \f5bezspline(\f2dst\fP, \f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
605 takes the same arguments as
607 but draws a quadratic B-spline (despite its name) rather than a polygon.
608 If the first and last points in
610 are equal, the spline has periodic end conditions.
612 \f5bezsplinepts(\f2pt\fP, \f2npt\fP, \f2pp\fP)
616 a list of points making up the open polygon that
619 The caller is responsible for freeing
622 \f5fillbezier(\f2dst\fP, \f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
631 \f5fillbezspline(\f2dst\fP, \f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP)
635 but fills the quadratic B-spline rather than the polygon outlined by
637 The spline is closed with a line if necessary.
639 \f5ellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP)
643 an ellipse centered on
645 with horizontal and vertical semiaxes
649 The source is aligned so
657 The ellipse is drawn with thickness
660 \f5fillellipse(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP)
664 but fills the ellipse rather than outlining it.
666 \f5arc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
670 but draws only that portion of the ellipse starting at angle
672 and extending through an angle of
674 The angles are measured in degrees counterclockwise from the positive
678 \f5fillarc(\f2dst\fP, \f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP, \f2alpha\fP, \f2phi\fP)
682 but fills the sector with the source color.
684 \f5icossin(\f2deg\fP, \f2cosp\fP, \f2sinp\fP)
690 scaled integers representing the cosine and sine of the angle
692 measured in integer degrees.
693 The values are scaled so cos(0) is 1024.
695 \f5icossin2(\f2x\fP, \f2y\fP, \f2cosp\fP, \f2sinp\fP)
699 with the angle represented not in degrees but implicitly by the point
710 .BI border( dst\fP,\fP\ r\fP,\fP\ i\fP,\fP\ color\fP,\fP\ sp\fP)
712 draws an outline of rectangle
716 The outline has width
718 if positive, the border goes inside the rectangle; negative, outside.
719 The source is aligned so
724 .BI string( dst\fP,\fP\ p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ s )
728 characters specified by the string
732 it is equivalent to a series of calls to
736 and masks determined by the character shapes.
737 The text is positioned with the left of the first character at
739 and the top of the line of text at
741 The source is positioned so
752 that is the position of the next character that would be drawn if the string were longer.
754 For characters with undefined
755 or zero-width images in the font, the character at font position 0 (NUL) is drawn.
757 The other string routines are variants of this basic form, and
758 have names that encode their variant behavior.
759 Routines whose names contain
761 accept a string of Runes rather than
768 that defines the number of characters to draw rather than accepting a NUL-terminated
772 draw the background behind the characters in the specified color
777 normally the text is drawn leaving the background intact.
781 captures all this behavior into a single operator. Whether it draws a
784 or Rune string depends on whether
788 is null (the string length is always determined by
792 is non-null, it is used as a background color.
795 argument allows further management of clipping when drawing the string;
796 it is intersected with the usual clipping rectangles to further limit the extent of the text.
798 .BI drawsetdebug( on )
799 Turns on or off debugging output (usually
800 to a serial line) according to whether
804 .B /usr/local/plan9/src/libdraw
813 ``Compositing Digital Images'',
814 .I "Computer Graphics
815 (Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.
817 These routines call the graphics error function on fatal errors.
819 Anti-aliased characters can be drawn by defining a font
820 with multiple bits per pixel, but there are
821 no anti-aliasing geometric primitives.
