20060303-partial

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.