diff options
Diffstat (limited to 'man/2/draw-image')
| -rw-r--r-- | man/2/draw-image | 909 |
1 files changed, 909 insertions, 0 deletions
diff --git a/man/2/draw-image b/man/2/draw-image new file mode 100644 index 00000000..477e69e0 --- /dev/null +++ b/man/2/draw-image @@ -0,0 +1,909 @@ +.TH DRAW-IMAGE 2 +.SH NAME +Image \- +pictures and drawing +.SH SYNOPSIS +.EX +include "draw.m"; +draw := load Draw Draw->PATH; + +# compositing operators +SinD: con 1<<3; +DinS: con 1<<2; +SoutD: con 1<<1; +DoutS: con 1<<0; + +S: con SinD|SoutD; +SoverD: con SinD|SoutD|DoutS; +SatopD: con SinD|DoutS; +SxorD: con SoutD|DoutS; + +D: con DinS|DoutS; +DoverS: con DinS|DoutS|SoutD; +DatopS: con DinS|SoutD; +DxorS: con DoutS|SoutD; + +Clear: con 0; + +Image: adt +{ + r: Rect; + clipr: Rect; + chans: Chans; + depth: int; + repl: int; + + display: ref Display; + screen: ref Screen; + + draw: fn(dst: self ref Image, r: Rect, src: ref Image, + mask: ref Image, p: Point); + drawop: fn(dst: self ref Image, r: Rect, src: ref Image, + mask: ref Image, p: Point, op: int); + gendraw: fn(dst: self ref Image, r: Rect, src: ref Image, + p0: Point, mask: ref Image, p1: Point); + gendrawop: fn(dst: self ref Image, r: Rect, src: ref Image, + p0: Point, mask: ref Image, p1: Point, op: int); + line: fn(dst: self ref Image, p0,p1: Point, + end0,end1,thick: int, + src: ref Image, sp: Point); + lineop: fn(dst: self ref Image, p0,p1: Point, + end0,end1,thick: int, + src: ref Image, sp: Point, op: int); + poly: fn(dst: self ref Image, p: array of Point, + end0,end1,thick: int, + src: ref Image, sp: Point); + polyop: fn(dst: self ref Image, p: array of Point, + end0,end1,thick: int, + src: ref Image, sp: Point, op: int); + bezspline: fn(dst: self ref Image, p: array of Point, + end0,end1,thick: int, + src: ref Image, sp: Point); + bezsplineop: fn(dst: self ref Image, p: array of Point, + end0,end1,thick: int, + src: ref Image, sp: Point, op: int); + fillpoly: fn(dst: self ref Image, p: array of Point, + wind: int, src: ref Image, sp: Point); + fillpolyop: fn(dst: self ref Image, p: array of Point, + wind: int, src: ref Image, sp: Point, op: int); + fillbezspline: fn(dst: self ref Image, p: array of Point, + wind: int, src: ref Image, sp: Point); + fillbezsplineop: fn(dst: self ref Image, p: array of Point, + wind: int, src: ref Image, sp: Point, op: int); + ellipse: fn(dst: self ref Image, c: Point, a, b, + thick: int, src: ref Image, sp: Point); + ellipseop: fn(dst: self ref Image, c: Point, a, b, + thick: int, src: ref Image, sp: Point, op: int); + fillellipse:fn(dst: self ref Image, c: Point, a, b: int, + src: ref Image, sp: Point); + fillellipseop:fn(dst: self ref Image, c: Point, a, b: int, + src: ref Image, sp: Point, op: int); + arc: fn(dst: self ref Image, c: Point, a, b, thick: int, + src: ref Image, sp: Point, alpha, phi: int); + arcop: fn(dst: self ref Image, c: Point, a, b, thick: int, + src: ref Image, sp: Point, + alpha, phi: int, op: int); + fillarc: fn(dst: self ref Image, c: Point, a, b: int, + src: ref Image, sp: Point, alpha, phi: int); + fillarcop: fn(dst: self ref Image, c: Point, a, b: int, + src: ref Image, sp: Point, + alpha, phi: int, op: int); + bezier: fn(dst: self ref Image, a,b,c,d: Point, + end0,end1,thick: int, + src: ref Image, sp: Point); + bezierop: fn(dst: self ref Image, a,b,c,d: Point, + end0,end1,thick: int, + src: ref Image, sp: Point, op: int); + fillbezier: fn(dst: self ref Image, a,b,c,d: Point, wind:int, + src: ref Image, sp: Point); + fillbezierop: fn(dst: self ref Image, a,b,c,d: Point, wind:int, + src: ref Image, sp: Point, op: int); + arrow: fn(a,b,c: int): int; + text: fn(dst: self ref Image, p: Point, src: ref Image, + sp: Point, font: ref Font, str: string): Point; + textop: fn(dst: self ref Image, p: Point, src: ref Image, + sp: Point, font: ref Font, str: string, + op: int): Point; + textbg: fn(dst: self ref Image, p: Point, src: ref Image, + sp: Point, font: ref Font, str: string, + bg: ref Image, bgp: Point): Point; + textbgop: fn(dst: self ref Image, p: Point, src: ref Image, + sp: Point, font: ref Font, str: string, + bg: ref Image, bgp: Point, op: int): Point; + border: fn(dst: self ref Image, r: Rect, i: int, + src: ref Image, sp: Point); + borderop: fn(dst: self ref Image, r: Rect, i: int, + src: ref Image, sp: Point, op: int); + + readpixels: fn(src: self ref Image, r: Rect, + data: array of byte): int; + writepixels:fn(dst: self ref Image, r: Rect, + data: array of byte): int; + name: fn(im: self ref Image, s: string, in: int): int; + top: fn(win: self ref Image); + bottom: fn(win: self ref Image); + flush: fn(win: self ref Image, func: int); + origin: fn(win: self ref Image, log, scr: Point): int; +}; +.EE +.SH DESCRIPTION +The +.B Image +type defines rectangular pictures and the methods to draw upon them; +it is also the building block for higher level objects such as +windows and fonts. +In particular, a window is represented as an +.BR Image ; +no special operators are needed to draw on a window. +Off-screen images can have an alpha channel, which gives each pixel an opacity +factor, which in turn allows non-rectangular images to be defined +(ie, pixels made fully transparent by the alpha channel +do not appear when the image is displayed). +Many drawing operations allow images to be shaped, or partial transparency added, by using the alpha +channel of another image as a mask (also called a `matte'). +There are two functions in +.B Image +for each such operation. +One has an +.B op +suffix, and takes an explicit image compositing operator: +.BR S , +.BR D , +.BR SinD , ..., +.BR SoverD +and so on. +(See the Porter-Duff paper mentioned below for the meaning of each operation.) +The other function (without the +.B op +suffix) provides as its default operation the most common operation, +.BR SoverD , +by which the source image, within its matte, is drawn over the destination image. +.PP +An +.B Image +has a pixel channel structure as described in +.IR colour (6), +represented by a value of the +.B Chans +adt, +defined in +.IR draw-display (2). +The channel structure of an image is fixed when the image is allocated. +.PP +.B Image +has the following components: +.TP 10 +.B display +Tells on which display the image resides. +.TP +.B screen +If the image is a window on a +.B Screen +(see +.IR draw-screen (2)), +this field refers to that screen; otherwise it is nil. +.TP +.B r +The coordinates of the rectangle in the plane for which the +.B Image +has defined pixel values. +It should not be modified after the image is created. +.TP +.B clipr +The clipping rectangle: operations that read or write +the image will not access pixels outside +.BR clipr . +Frequently, +.B clipr +is the same as +.BR Image.r , +but it may differ; see in particular the discussion of +.BR Image.repl . +The clipping region may be modified dynamically. +.TP +.B chans +The pixel channel structure of the image; the value +should not be modified after the image is created. +.TP +.B depth +The number of bits per pixel in the picture: +it is simply a convenience since it is necessarily equal to +.BR chans.depth() , +and it should not be modified after the image is created. +.TP +.B repl +A boolean value specifying whether the image is tiled to cover +the plane when used as a source for a drawing operation. +If +.B Image.repl +is zero, operations are restricted to the intersection of +.B Image.r +and +.BR Image.clipr . +If +.B Image.repl +is set, +.B Image.r +defines the tile to be replicated and +.B Image.clipr +defines the portion of the plane covered by the tiling, in other words, +.B Image.r +is replicated to cover +.BR Image.clipr ; +in such cases +.B Image.r +and +.B Image.clipr +are independent. +.IP +For example, a replicated image with +.B Image.r +set to ((0,\ 0),\ (1,\ 1)) and +.B Image.clipr +set to ((0,\ 0),\ (100,\ 100)), +with the single pixel of +.B Image.r +set to blue, +behaves identically to an image with +.B Image.r +and +.B Image.clipr +both set to ((0,\ 0),\ (100,\ 100)) and all pixels set to blue. +However, +the first image requires far less memory. +The replication flag may be modified dynamically along with the clipping +rectangle. +.TP +.IB dst .draw( r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p\fP ) +.PD0 +.TP +.IB dst .drawop( r\fP,\fP\ src\fP,\fP\ mask\fP,\fP\ p\fP,\fP\ op ) +.PD +.B Draw +is the standard drawing function. +Only those pixels within the intersection of +.IB dst .r +and +.IB dst .clipr +will be affected; +.B draw +ignores +.IB dst .repl\fR. +The operation proceeds as follows +(this is a description of the behavior, not the implementation): +.RS +.IP 1. +If +.B repl +is set in +.I src +or +.IR mask , +replicate their contents to fill +their clip rectangles. +.IP 2. +Translate +.I src +and +.I mask +so +.I p +is aligned with +.IB r .min\fR. +.IP 3. +Set +.I r +to the intersection of +.I r +and +.IB dst .r\fR. +.IP 4. +Intersect +.I r +with +.IB src .clipr\fR. +If +.IB src .repl +is false, also intersect +.I r +with +.IB src .r\fR. +.IP 5. +Intersect +.I r +with +.IB mask .clipr\fR. +If +.IB mask .repl +is false, also intersect +.I r +with +.IB mask .r\fR. +.IP 6. +For each location in +.IR r , +combine the +.I dst +pixel using the alpha value corresponding to the +.I mask +pixel. +If the +.I mask +has an explicit alpha channel, the alpha value corresponding to the +.I mask +pixel is simply that pixel's alpha channel. +Otherwise, the alpha value is the NTSC greyscale equivalent of the colour value, +with white meaning opaque and black transparent. +.RE +.IP +In terms of the Porter-Duff compositing algebra, +.I draw +replaces the +.I dst +pixels with +.RI ( src +in +.IR mask ) +over +.IR dst . +.I Drawop +is almost identical, but applies the compositing operation +.I op +instead: +.RI ( src +in +.IR mask ) +.I op +.IR dst . +.IP +The various +pixel channel formats +involved need not be identical. +If the channels involved are smaller than 8-bits, they will +be promoted before the calculation by replicating the extant bits; +after the calculation, they will be truncated to their proper sizes. +For +.B draw +and +.B gendraw +only, +if +.I mask +is nil, no mask is used. +.TP +\f2dst\fP.\f5gendraw(\f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\fP)\fP +.PD0 +.TP +\f2dst\fP.\f5gendrawop(\f2r\fP, \f2src\fP, \f2p0\fP, \f2mask\fP, \f2p1\fP\f5, \f2op\fP)\fP +.PD +Similar to \f5draw()\fP except that it aligns the source and mask differently: +.I src +is aligned so +.I p0 +corresponds to +.IB r . min +and +.I mask +is aligned so +.I p1 +corresponds to +.IB r . min . +For most purposes with simple masks and source images, +.B draw +is sufficient, but +.B gendraw +is the general operator and the one the other drawing primitives are built upon. +.TP +\f2dst\fP.\f5line(\f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5lineop(\f2p0\fP, \f2p1\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Line +draws in +.I dst +a line of width +.RI 1+2* thick +pixels joining points +.I p0 +and +.IR p1 . +The line is drawn using pixels from the +.I src +image aligned so +.I sp +in the source corresponds to +.I p0 +in the destination. +The line touches both +.I p0 +and +.IR p1 , +and +.I end0 +and +.I end1 +specify how the ends of the line are drawn. +.B Draw->Endsquare +terminates the line perpendicularly to the direction of the line; a thick line with +.B Endsquare +on both ends will be a rectangle. +.B Draw->Enddisc +terminates the line by drawing a disc of diameter +.RI 1+2* thick +centered on the end point. +.B Draw->Endarrow +terminates the line with an arrowhead whose tip touches the endpoint. +See the description of +.B arrow +for more information. +.IP +.B Line +and the other geometrical operators are equivalent to calls to +.B gendraw +using a mask produced by the geometric procedure. +.TP +\f2dst\fP.\f5poly(\f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5polyop(\f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Poly +draws a general polygon; it +is equivalent to a series of calls to +.B line +joining adjacent points in the array of +.B Points +.IR p . +The ends of the polygon are specified as in +.BR line ; +interior lines are terminated with +.B Enddisc +to make smooth joins. +The source is aligned so +.I sp +corresponds to +.IB p [0]\f1. +.TP +\f2dst\fP.\f5bezspline(\f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5bezsplineop(\f2p\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Bezspline +takes the same arguments as +.B poly +but draws a quadratic B-spline (despite its name) rather than a polygon. +If the first and last points in +.I p +are equal, the spline has periodic end conditions. +.TP +\f2dst\fP.\f5fillpoly(\f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5fillpolyop(\f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Fillpoly +is like +.B poly +but fills in the resulting polygon rather than outlining it. +The source is aligned so +.I sp +corresponds to +.IB p [0]\f1. +The winding rule parameter +.I wind +resolves ambiguities about what to fill if the polygon is self-intersecting. +If +.I wind +is +.BR ~0 , +a pixel is inside the polygon if the polygon's winding number about the point +is non-zero. +If +.I wind +is 1, +a pixel is inside if the winding number is odd. +Complementary values (0 or ~1) cause outside pixels to be filled. +The meaning of other values is undefined. +The polygon is closed with a line if necessary. +.TP +\f2dst\fP.\f5fillbezspline(\f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5fillbezsplineop(\f2p\fP, \f2wind\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Fillbezspline +is like +.B fillpoly +but fills the quadratic B-spline rather than the polygon outlined by +.IR p . +The spline is closed with a line if necessary. +.TP +\f2dst\fP.\f5ellipse(\f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5ellipseop(\f2c\fP, \f2a\fP, \f2b\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Ellipse +draws in +.I dst +an ellipse centered on +.I c +with horizontal and vertical semiaxes +.I a +and +.IR b . +The source is aligned so +.I sp +in +.I src +corresponds to +.I c +in +.IR dst . +The ellipse is drawn with thickness +.RI 1+2* thick . +.TP +\f2dst\fP.\f5fillellipse(\f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5fillellipseop(\f2c\fP, \f2a\fP, \f2b\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Fillellipse +is like +.B ellipse +but fills the ellipse rather than outlining it. +.TP +.IB dst .arc(\fIc\fP,\ \fIa\fP,\ \fIb\fP,\ \fIthick\fP,\ \fIsrc\fP,\ \fIsp\fP,\ \fIalpha\fP,\ \fIphi\fP) +.PD0 +.TP +.IB dst .arcop(\fIc\fP,\ \fIa\fP,\ \fIb\fP,\ \fIthick\fP,\ \fIsrc\fP,\ \fIsp\fP,\ \fIalpha\fP,\ \fIphi\fP,\ \fIop\fP) +.PD +.I Arc +is like +.IR ellipse , +but draws only that portion of the ellipse starting at angle +.I alpha +and extending through an angle of +.IR phi . +The angles are measured in degrees counterclockwise from the positive +.I x +axis. +.TP +.IB dst .fillarc(\fIc\fP,\ \fIa\fP,\ \fIb\fP,\ \fIsrc\fP,\ \fIsp\fP,\ \fIalpha\fP,\ \fIphi\fP) +.PD0 +.TP +.IB dst .fillarcop(\fIc\fP,\ \fIa\fP,\ \fIb\fP,\ \fIsrc\fP,\ \fIsp\fP,\ \fIalpha\fP,\ \fIphi\fP,\ \fIop\fP) +.PD +.I Fillarc +is like +.IR arc , +but fills the sector with the source color. +.TP +\f2dst\fP.\f5bezier(\f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5bezierop(\f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2end0\fP, \f2end1\fP, \f2thick\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Bezier +draws the +cubic Bezier curve defined by +.B Points +.IR a , +.IR b , +.IR c , +and +.IR d . +The end styles are determined by +.I end0 +and +.IR end1 ; +the thickness of the curve is +.RI 1+2* thick . +The source is aligned so +.I sp +in +.I src +corresponds to +.I a +in +.IR dst . +.TP +\f2dst\fP.\f5fillbezier(\f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP) +.PD0 +.TP +\f2dst\fP.\f5fillbezierop(\f2a\fP, \f2b\fP, \f2c\fP, \f2d\fP, \f2wind\fP, \f2src\fP, \f2sp\fP, \f2op\fP) +.PD +.B Fillbezier +is to +.B bezier +as +.B fillpoly +is to +.BR poly . +.TP +.BI arrow( "a,\ b,\ c" ) +.B Arrow +is a function to describe general arrowheads; its result is passed as +.I end +parameters to +.BR line , +.BR poly , +etc. +If all three parameters are zero, it produces the default arrowhead, +otherwise, +.I a +sets the distance along line from end of the regular line to tip, +.I b +sets the distance along line from the barb to the tip, +and +.I c +sets the distance perpendicular to the line from edge of line to the tip of the barb, +all in pixels. +.TP +.IB dst .border( r\fP,\fP\ i\fP,\fP\ src\fP,\fP\ sp\fP) +.PD0 +.TP +.IB dst .borderop( r\fP,\fP\ i\fP,\fP\ src\fP,\fP\ sp\fP,\ \f2op\fP) +.PD +.I Border +draws in +.I dst +an outline of rectangle +.I r +in the given +.I src +colour. +The outline has width +.IR i ; +if positive, the border goes inside the rectangle; negative, outside. +The source is aligned so +.I sp +corresponds to +.IB r .min . +.TP +.IB dst .text( p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ str\fP) +.PD0 +.TP +.IB dst .textop( p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ str\fP,\ \f2op\fP) +.TP +.IB dst .textbg( p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ str\fP,\ \f2bg\fP,\ \f2bgp\fP) +.PD0 +.TP +.IB dst .textbgop( p\fP,\fP\ src\fP,\fP\ sp\fP,\fP\ font\fP,\fP\ str\fP,\ \f2bg\fP,\ \f2bgp\fP,\ \f2op\fP) +.PD +.B Text +draws in +.I dst +characters specified by the string +.I str +and font +.IR font ; +it is equivalent to a series of calls to +.B gendraw +using source +.I src +and masks determined by the character shapes. +The text is positioned with the left of the first character at +.IB p .x +and the top of the line of text at +.IB p .y\f1. +The source is positioned so +.I sp +in +.I src +corresponds to +.I p +in +.IR dst . +.B Text +returns a +.B Point +that is the position of the next character that would be drawn if the string were longer. +.IP +For characters with undefined +or zero-width images in the font, the character at font position 0 (NUL) is drawn. +.IP +.B Text +draws the text leaving the background intact. +.B Textbg +draws the background colour +.I bg +behind the characters, with the alignment specified by point +.IR bgp ; +it is otherwise the same as +.BR text . +.TP +.IB src .readpixels( r\fP,\fP\ data ) +.B Readpixels +fills the +.I data +array with pixels from the specified rectangle of the +.I src +image. +The pixels are presented one horizontal line at a time, +starting with the top-left pixel of +.IR r . +Each scan line starts with a new byte in the array, +leaving the last byte of the previous line partially empty, if necessary. +Pixels are packed as tightly as possible within +.IR data , +regardless of the rectangle being extracted. +Bytes are filled from most to least significant bit order, +as the +.I x +coordinate increases, aligned so +.IR x =0 +would appear as the leftmost pixel of its byte. +Thus, for a 1-bit deep greyscale image, +the pixel at +.I x +offset 165 within the rectangle will be in a +.I data +byte with mask value +.B 16r04 +regardless of the overall +rectangle: 165 mod 8 equals 5, and +.B "16r80\ >>\ 5" equals +.BR 16r04 . +It is an error to call +.B readpixels +with an array that is too small to hold the rectangle's pixels. +The return value is the number of bytes copied. +The arrangement of pixels in arrays of bytes is described in +.IR image (6). +.TP +.IB dst .writepixels( r\fP,\fP\ data ) +.B Writepixels +copies pixel values from the +.I data +array to the specified rectangle in the +.I dst +image. +The format of the data is that produced by +.BR readpixels . +The return value is the number of bytes copied. +It is an error to call +.B writepixels +with an array that is too small to fill the rectangle. +.TP +.IB im .name( s , in ) +Publish the image +.I im +on its display under name +.IR s , +if +.I in is non-zero; +otherwise, +.I s +must be an already published name and it is withdrawn from publication. +A published image can be retrieved using +.B Display.namedimage +(see +.IR draw-display (2)). +This function returns -1 on error, typically because the name is already in use +(for +.I in +non-zero), or does not exist +(for +.I in +zero). +.TP +.IB win .top() +If the image +.I win +is a window, +.B top +pulls it to the ``top'' of the stack of windows on its +.BR Screen , +perhaps obscuring other images. +If +.I win +is not a window, +.B top +has no effect. +.TP +.IB win .bottom() +If the image +.I win +is a window, +.B bottom +pulls it to the ``bottom'' of the stack of windows on its +.BR Screen , +perhaps obscuring it. +If +.I win +is not a window, +.B bottom +has no effect. +.TP +.IB image .flush( flag ) +The connection to a display has a buffer used to gather graphics requests +generated by calls to the draw library. +By default, the library flushes the buffer at the conclusion of any +call that affects the visible display +image itself. +The +.B flush +routine allows finer control of buffer management. +The +.I flag +has three possible values: +.B Flushoff +turns off all automatic flushing caused by writes to +.IR image , +typically a window or the display image itself +(buffers may still be written when they fill or when other objects on the display +are modified); +.B Flushnow +causes the buffer to be flushed immediately; +and +.B Flushon +restores the default behaviour. +.TP +\f2win\fP.\f5origin(\f2log\fP, \f2scr\fP) +When a window is created (see +.IR draw-screen (2)), +the coordinate system within the window is identical to that of the screen: +the upper left corner of the window rectangle is its physical location on the display, +not for example (0, 0). +This symmetry may be broken, however: +.B origin +allows control of the location of the window on the display and the coordinate +system used by programs drawing on the window. +The first argument, +.IR log , +sets the upper left corner of the logical (in-window) coordinate system without +changing the position of the window on the screen. +The second argument, +.IR scr , +sets the upper left corner of physical (on-screen) coordinate system, that is, the +window's location on the display, without changing the internal coordinate system. +Therefore, changing +.I scr +without changing +.I log +moves the window without requiring the client using it to be notified of the change; +changing +.I log +without changing +.I scr +allows the client to set up a private coordinate system regardless of the window's +location. +It is permissible for values of +.I scr +to move some or all of the window off screen. +.B Origin +returns \-1 if the image is not a window or, in the case of changes to +.IR scr , +if there are insufficient resources available to move the window; +otherwise it returns 1. +.SH SOURCE +.B /libdraw +.SH SEE ALSO +.IR draw-intro (2), +.IR draw-display (2), +.IR draw-point (2), +.IR draw-rect (2), +.IR draw-screen (2), +.IR colour (6), +.IR image (6), +.IR font (6) +.IR utf (6) +.PP +T. Porter, T. Duff. +``Compositing Digital Images'', +.I "Computer Graphics +(Proc. SIGGRAPH), 18:3, pp. 253-259, 1984. +.SH DIAGNOSTICS +These functions raise exceptions if argument images are nil, +except for +.B draw +and +.B gendraw +where the mask image is optional and may be nil. +.SH BUGS +Anti-aliased characters can be drawn by defining a font +with multiple bits per pixel, but there are +no anti-aliasing geometric primitives. |