DRAW-IMAGE(2) DRAW-IMAGE(2)
NAME
Image - pictures and drawing
SYNOPSIS
include "draw.m";
draw := load Draw Draw->PATH;
Image: adt
{
r: Rect;
clipr: Rect;
ldepth: 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);
gendraw: fn(dst: self ref Image, r: Rect, src: ref Image,
p0: Point, mask: ref Image, p1: Point);
line: fn(dst: self ref Image, p0,p1: Point,
end0,end1,thick: int, src: ref Image, sp: Point);
poly: fn(dst: self ref Image, p: array of Point,
end0,end1,thick: int, src: ref Image, sp: Point);
bezspline: fn(dst: self ref Image, p: array of Point,
end0,end1,thick: int, src: ref Image, sp: Point);
fillpoly: fn(dst: self ref Image, p: array of Point,
wind: int, src: ref Image, sp: Point);
fillbezspline: fn(dst: self ref Image, p: array of Point,
wind: int, src: ref Image, sp: Point);
ellipse: fn(dst: self ref Image, c: Point, a, b,
thick: int, src: ref Image, sp: Point);
fillellipse:fn(dst: self ref Image, c: Point, a, b: int,
src: ref Image, sp: Point);
bezier: fn(dst: self ref Image, a,b,c,d: Point,
end0,end1,thick: int, src: ref Image, sp: Point);
fillbezier: fn(dst: self ref Image, a,b,c,d: Point, wind:int,
src: ref Image, sp: Point);
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;
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;
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;
Page 1 Plan 9 (printed 12/22/24)
DRAW-IMAGE(2) DRAW-IMAGE(2)
};
DESCRIPTION
The 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 Image; no special operators are
needed to draw on a window.
r The coordinates of the rectangle in the plane for
which the Image has defined pixel values. It
should not be modified after the image is created.
clipr The clipping rectangle: operations that read or
write the image will not access pixels outside
clipr. Frequently, clipr is the same as Image.r,
but it may differ; see in particular the discus-
sion of Image.repl. The clipping region may be
modified dynamically.
ldepth The log base 2 of the number of bits per pixel in
the picture: 0 for one bit per pixel, 3 for eight
bits per pixel, etc. The library supports
Image.ldepth values 0, 1, 2, and 3 only. The
value should not be modified after the image is
created.
repl A boolean value specifying whether the image is
tiled to cover the plane when used as a source for
a drawing operation. If Image.repl is zero, oper-
ations are restricted to the intersection of
Image.r and Image.clipr. If Image.repl is set,
Image.r defines the tile to be replicated and
Image.clipr defines the portion of the plane cov-
ered by the tiling, in other words, Image.r is
replicated to cover Image.clipr; in such cases
Image.r and Image.clipr are independent.
For example, a replicated image with Image.r set
to ((0, 0), (1, 1)) and Image.clipr set to
((0, 0), (100, 100)), with the single pixel of
Image.r set to blue, behaves identically to an
image with Image.r and 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.
dst.draw(r, src, mask, p)
Draw is the standard drawing function. Only those
pixels within the intersection of dst.r and
dst.clipr will be affected; draw ignores dst.repl.
Page 2 Plan 9 (printed 12/22/24)
DRAW-IMAGE(2) DRAW-IMAGE(2)
The operation proceeds as follows:
1. If repl is set in src or mask, replicate
their contents to fill their clip rectangles.
2. Translate src and mask so p is aligned with
r.min.
3. Set r to the intersection of r and dst.r.
4. Intersect r with src.clipr. If src.repl is
false, also intersect r with src.r.
5. Intersect r with mask.clipr. If mask.repl is
false, also intersect r with mask.r.
6. For each location in r for which the mask
pixel is non-zero, set the dst pixel to be
the value of the src pixel.
The various ldepth values involved need not be
identical. If the src or mask images are single
replicated pixels, any ldepth is fine. Otherwise,
if their ldepth is not the same as the destina-
tion, they must have ldepth value 0. For draw and
gendraw only, if mask is nil, a mask of all ones
is used. These restrictions may weaken in later
implementations.
display Tells on which display the image resides.
screen If the image is a window on a Screen (see draw-
screen(2)), this field refers to that screen; oth-
erwise it is nil.
dst.gendraw(r, src, p0, mask, p1)
Similar to draw() except that it aligns the source
and mask differently: src is aligned so p0 corre-
sponds to r.min and mask is aligned so p1 corre-
sponds to r.min. For most purposes with simple
masks and source images, draw is sufficient, but
gendraw is the general operator and the one the
other drawing primitives are built upon.
dst.line(p0, p1, end0, end1, thick, src, sp)
Line draws in dst a line of width 1+2*thick pixels
joining points p0 and p1. The line is drawn using
pixels from the src image aligned so sp in the
source corresponds to p0 in the destination. The
line touches both p0 and p1, and end0 and end1
specify how the ends of the line are drawn.
Draw->Endsquare terminates the line
Page 3 Plan 9 (printed 12/22/24)
DRAW-IMAGE(2) DRAW-IMAGE(2)
perpendicularly to the direction of the line; a
thick line with Endsquare on both ends will be a
rectangle. Draw->Enddisc terminates the line by
drawing a disc of diameter 1+2*thick centered on
the end point. Draw->Endarrow terminates the line
with an arrowhead whose tip touches the endpoint.
See the description of arrow for more information.
Line and the other geometrical operators are
equivalent to calls to gendraw using a mask pro-
duced by the geometric procedure.
dst.poly(p, end0, end1, thick, src, sp)
Poly draws a general polygon; it is equivalent to
a series of calls to line joining adjacent points
in the array of Points p. The ends of the polygon
are specified as in line; interior lines are ter-
minated with Enddisc to make smooth joins. The
source is aligned so sp corresponds to p[0].
dst.bezspline(p, end0, end1, thick, src, sp)
Bezspline takes the same arguments as poly but
draws a quadratic B-spline (despite its name)
rather than a polygon. If the first and last
points in p are equal, the spline has periodic end
conditions.
dst.fillpoly(p, wind, src, sp)
Fillpoly is like poly but fills in the resulting
polygon rather than outlining it. The source is
aligned so sp corresponds to p[0]. The winding
rule parameter wind resolves ambiguities about
what to fill if the polygon is self-intersecting.
If wind is ~0, a pixel is inside the polygon if
the polygon's winding number about the point is
non-zero. If 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 mean-
ing of other values is undefined. The polygon is
closed with a line if necessary.
dst.fillbezspline(p, wind, src, sp)
Fillbezspline is like fillpoly but fills the qua-
dratic B-spline rather than the polygon outlined
by p. The spline is closed with a line if neces-
sary.
dst.ellipse(c, a, b, thick, src, sp)
Ellipse draws in dst an ellipse centered on c with
horizontal and vertical semiaxes a and b. The
source is aligned so sp in src corresponds to c in
dst. The ellipse is drawn with thickness
Page 4 Plan 9 (printed 12/22/24)
DRAW-IMAGE(2) DRAW-IMAGE(2)
1+2*thick.
dst.fillellipse(c, a, b, src, sp)
Fillellipse is like ellipse but fills the ellipse
rather than outlining it.
dst.bezier(a, b, c, d, end0, end1, thick, src, sp)
Bezier draws the cubic Bezier curve defined by
Points a, b, c, and d. The end styles are deter-
mined by end0 and end1; the thickness of the curve
is 1+2*thick. The source is aligned so sp in src
corresponds to a in dst.
dst.fillbezier(a, b, c, d, wind, src, sp)
Fillbezier is to bezier as fillpoly is to poly.
arrow(a, b, c)
Arrow is a function to describe general arrow-
heads; its result is passed as end parameters to
line, poly, etc. If all three parameters are
zero, it produces the default arrowhead, other-
wise, a sets the distance along line from end of
the regular line to tip, b sets the distance along
line from the barb to the tip, and c sets the dis-
tance perpendicular to the line from edge of line
to the tip of the barb, all in pixels.
dst.text(p, src, sp, font, str)
Text draws in dst characters specified by the
string str and font font; it is equivalent to a
series of calls to gendraw using source src and
masks determined by the character shapes. The
text is positioned with the left of the first
character at p.x and the top of the line of text
at p.y. The source is positioned so sp in src
corresponds to p in dst. Text returns a Point that
is the position of the next character that would
be drawn if the string were longer.
For characters with undefined or zero-width images
in the font, the character at font position 0
(NUL) is drawn.
src.readpixels(r, data)
Readpixels fills the data array with pixels from
the specified rectangle of the src image. The
pixels are presented one horizontal line at a
time, starting with the top-left pixel of r. Each
scan line starts with a new byte in the array,
leaving the last byte of the previous line par-
tially empty, if necessary. Pixels are packed as
tightly as possible within data, regardless of the
Page 5 Plan 9 (printed 12/22/24)
DRAW-IMAGE(2) DRAW-IMAGE(2)
rectangle being extracted. Bytes are filled from
most to least significant bit order, as the x
coordinate increases, aligned so x=0 would appear
as the leftmost pixel of its byte. Thus, for
ldepth 0, the pixel at x offset 165 within the
rectangle will be in a data byte with mask value
16r04 regardless of the overall rectangle: 165 mod
8 equals 5, and 16r80 >> 5 equals 16r04. It is an
error to call readpixels with an array that is too
small to hold the rectangle's pixels. The return
value is the number of bytes copied.
dst.writepixels(r, data)
Writepixels copies pixel values from the data
array to the specified rectangle in the dst image.
The format of the data is that produced by
readpixels. The return value is the number of
bytes copied. It is an error to call writepixels
with an array that is too small to fill the rect-
angle.
win.top() If the image win is a window, top pulls it to the
``top'' of the stack of windows on its Screen,
perhaps obscuring other images. If win is not a
window, top has no effect.
win.bottom()
If the image win is a window, bottom pulls it to
the ``bottom'' of the stack of windows on its
Screen, perhaps obscuring it. If win is not a
window, bottom has no effect.
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 flush rou-
tine allows finer control of buffer management.
The flag has three possible values: Flushoff turns
off all automatic flushing caused by writes to
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 mod-
ified); Flushnow causes the buffer to be flushed
immediately; and Flushon restores the default
behaviour.
win.origin(log, scr)
When a window is created (see draw-screen(2)), the
coordinate system within the window is identical
to that of the screen: the upper left corner of
Page 6 Plan 9 (printed 12/22/24)
DRAW-IMAGE(2) DRAW-IMAGE(2)
the window rectangle is its physical location on
the display, not for example (0, 0). This symme-
try may be broken, however: 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, log, sets the
upper left corner of the logical (in-window) coor-
dinate system without changing the position of the
window on the screen. The second argument, 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 scr with-
out changing log moves the window without requir-
ing the client using it to be notified of the
change; changing log without changing scr allows
the client to set up a private coordinate system
regardless of the window's location. It is per-
missible for values of scr to move some or all of
the window off screen. Origin returns -1 if the
image is not a window or, in the case of changes
to scr, if there are insufficient resources avail-
able to move the window; otherwise it returns 1.
Page 7 Plan 9 (printed 12/22/24)