DRAW(3) DRAW(3)
NAME
draw - graphics device
SYNOPSIS
bind -b #d /dev
/dev/draw/new
/dev/draw/n/ctl
/dev/draw/n/data
/dev/draw/n/refresh
DESCRIPTION
The draw device serves a three-level file system providing
an interface to the graphics facilities of the system; the
Limbo Draw module (see draw-intro(2)) accesses the device to
implement its functions.
Each client of the device connects by opening /dev/draw/new
and reading back 7 decimal numbers, each 11 characters wide
followed by a blank: the connection number (n), the image id
(q.v.) of the display image (always zero), the ldepth of the
display image, and the min.x, min.y, max.x, and max.y of the
rectangle defining the display image. The client can then
open the directory /dev/draw/n/ to access the ctl, data, and
refresh files associated with the connection.
The ctl file accepts no messages; its only purpose is to
return the initialization information.
The data file accepts messages corresponding to procedures
in the Draw module: allocate a window or image, draw on the
image, paint text, etc. Some such messages generate data to
be returned to the client, which can recover it by reading
the data file.
The refresh file is read-only. As windows owned by the
client are uncovered, if they cannot be refreshed by the
server (such as when they have refresh functions associated
with them), a message is made available on the refresh file
reporting what needs to be repainted by the client. The
message has five decimal integers formatted as in the ctl
message: the image id of the window and the coordinates of
the rectangle that should be refreshed.
The draw device provides three types of graphical resource:
Images, Screens and Fonts. Resource instances have an iden-
tification number. Screen identifiers are global to the
device. All other identifiers are local to each client.
Page 1 Plan 9 (printed 4/25/24)
DRAW(3) DRAW(3)
Image is the fundamental resource type on which all drawing
primitives are performed. At client connection the physical
display is represented by Image 0.
A Screen manages a set of (overlapping) Images, handling Z-
order and position manipulation and the refreshing of
regions uncovered by such operations. When a Screen is cre-
ated it is associated with an Image on which to render
itself. New images can be associated with a screen when
they are created; they are then treated as windows on that
screen. Screens can be marked as public, meaning that other
clients can import their ID and create new windows on them.
A Font is an image with associated character data. The Font
image provides the bitmap of all the characters in the Font;
the character data is used by the string command to render
characters from the image.
Command Messages
Messages written to the data file take the form of a single
command code followed by command specific binary parameters.
The command is given by the byte code of a US-ASCII charac-
ter. Multibyte integer parameters are presented low-order
byte first. Points are two four-byte numbers: x and y.
Rectangles are four four-byte numbers: min.x, min.y, max.x,
and max.y. Any errors in the format of a message or its
parameter values result in the write (see sys-read(2))
request failing with an appropriate diagnostic message.
In the following list, the byte width of each parameter is
given in square brackets.
a id[4] screenid[4] refresh[1] ldepth[2] repl[1] R[4*4]
clipR[4*4] value[1]
Allocate an image with the given numeric id. The device
checks that id is unique within the id-space of the
client. If screenid is 0 the image is created as a
simple off-screen bitmap, otherwise it is created as a
window on the specified screen.
The refresh parameter specifies the refresh method to
use when on-screen images (windows) need updating. It
is ignored for off-screen images.
The refresh methods are:
Backup (0)
Modifications to covered areas of the image are written
to backing store. When an area is uncovered, the cor-
responding area of the screen image is refreshed from
the backing store. No notification is given via the
refresh file.
Page 2 Plan 9 (printed 4/25/24)
DRAW(3) DRAW(3)
Local (1)
No backing store is associated with the image. Opera-
tions only affect uncovered areas of the image on the
screen. No refresh notification is given via the
refresh file. This method is useful for images that
are constantly updated.
Remote (2)
No backing store is associated with the image. Opera-
tions only affect uncovered areas of the image on the
screen. When an area is uncovered, a refresh message
is buffered on the refresh file of the client that cre-
ated the image.
Ldepth is the log base 2 of the number of bits per pix-
els. This must match that of the associated screen.
If repl is non-zero the image behaves as if it tiles
the entire integer plane bounded by clipR. The rectan-
gle R gives the extent of the image. For windows, R
also gives the position of the image on the screen.
New windows are always created on top of the others on
the screen. The clipping rectangle of the image is
given by clipR. The pixels in the new image are
assigned the value palette index.
A id[4] imageid[4] fillid[4] public[1]
Create a new screen on the existing image given by
imageid. The image must not already be assigned to a
screen. The screen id must be unique on the device.
Fillid specifies the image used to paint the screen
background. This image should be tiled (repl != 0), or
be larger than the sreen image. If public is non-zero
then the screen is made available for use by other
clients.
c dstid[4] repl[1] clipR[4*4]
Set the repl flag and clipping rectangle clipR of the
existing image dstid.
x P[2*4]
Move the cursor to point P.
C id[4] hotspot[2*4]
Set the cursor image to that given by id. The hotspot
point is the offset added to the mouse position when
drawing the cursor image. The image given by id must
have ldepth 0.
d dstid[4] srcid[4] maskid[4] R[4*4] P0[2*4] P1[2*4]
The general drawing, or bitmap block transfer (bitblt)
command. The rectangle R specifies the region in the
dstid image to be modified. Pixel values are copied
Page 3 Plan 9 (printed 4/25/24)
DRAW(3) DRAW(3)
from the rectangle of the same size located at point P0
in the srcid image. Only those pixels in R of dstid
are copied for which the congruent pixel in the same
sized rectangle positioned at point P1 in the maskid
image have a non-zero value. The repl flag is honoured
when determining pixel values in the source and mask
images. The clipping rectangles and actual dimensions
of all the images are observed when determining which
pixels are to be copied.
e dstid[4] srcid[4] center[2*4] a[4] b[4] thick[4] sp[2*4]
alpha[4] phi[4]
Draw an ellipse or arc. The ellipse is drawn on the
dstid image using pixel values from the srcid image.
The point sp in the srcid image maps to the point
center in the dstid image.
The ellipse is centered on the point center in dstid.
The parameters a and b specify the horizontal and ver-
tical semiaxes. The outline of the ellipse is 1+2thick
pixels wide. An outline thicker than 1 pixel extends
equally inside and outside of the ellipse.
An arc of the ellipse is drawn if the most significant
bit (1<<31) of alpha is set. Alpha specifies the start
angle and phi gives the path angle of the arc. Angles
are given in degrees measured counterclockwise from the
positive x axis.
E dstid[4] srcid[4] center[2*4] a[4] b[4] thick[4] sp[2*4]
alpha[4] phi[4]
Draw a filled ellipse. Parameters are as for e, the
unfilled ellipse command. If an arc is specified then
the filled wedge defined by the arc is drawn.
f id[4]
Free the image specified by id. If id represents a
screen fill or image, then the resource will not be
released until the screen is freed.
F id[4]
Free the screen specified by id. A public screen is
only released when no other clients have a reference to
it. When a screen is freed, its image and fill
resources are also freed, invalidating their IDs.
i fontid[4] nchars[4] ascent[1]
Allocate a new font using the existing image fontid.
Nchars worth of character data is reserved for the
font. Ascent defines the distance from the top of the
font image to the baseline.
Page 4 Plan 9 (printed 4/25/24)
DRAW(3) DRAW(3)
l fontid[4] srcid[4] index[2] R[4*4] P[2*4] left[1] width[1]
Initialise a font character. Load the image and ren-
dering data for the character code index in font
fontid. The character bitmap is copied to the rectangle
R in the font image, from the same sized rectangle
positioned at point P in the srcid image.
When the character is rendered, using the s command, it
is drawn offset horizontally by left pixels to allow
for internal whitespace on the left of the character
image. Width specifies the width of the rendered char-
acter, not of its internal bitmap.
L dstid[4] p0[2*4] p1[2*4] end0[4] end1[4] radius[4]
srcid[4] sp[2*4]
Draw a line from p0 to p1 in dstid using pixels from
srcid. The point sp in srcid corresponds to the point
p0 in dstid. The thickness of the line is given by
1+2radius. The parameters end0 and end1 specify how
the respective ends of the line are drawn. The end
type is given by the low-order 5 bits of the parameter.
The following values can be used:
Endsquare (0)
The line is terminated perpendicularly to its direc-
tion.
Enddisc (1)
The line is terminated by a semi-circle of diameter
1+2radius, centered on the end-point.
Endarrow (2)
The remaining 27 high-order bits of the parameter spec-
ify how the arrow is drawn by partitioning the bits
into three 9-bit values: a, b and c. The 9 lower-order
bits give a, the 9 high-order bits give c. The parame-
ter a defines the distance from the tip to the point on
the line where the barb starts. The parameter b gives
the distance along the line from the tip to the tail of
the barb. If a = b a triangular arrow-head is formed.
If a < b a delta shaped arrow-head is formed. The
parameter c specifies the distance perpendicular from
the edge of the line to the barb.
o id[4] r.min[2*4] screenr.min[2*4]
Set the screen and logical origin of window id. If id
is not an on-screen image (window) the command does
nothing. The logical origin of the window, affecting
all drawing primitives on that window's image, is given
by the point r.min. The position of the window on its
screen is given by the point screenr.min.
Page 5 Plan 9 (printed 4/25/24)
DRAW(3) DRAW(3)
p dstid[4] n[2] end0[4] end1[4] radius[4] srcid[4] sp[2*4]
p0[2*4] dp[2*2*n]
Draw the polygon made up of n lines. The starting
point of the first line is given by p0. The (x, y) del-
tas of the remaining vertices are given by dp. The ends
of the polygon, end0 and end1, and the line radius are
treated as per the line (`L') command. Interior lines
are terminated with Enddisc, to give a smooth join.
The lines are drawn using pixel values from the srcid
image, where sp in srcid aligns with p0 in the destina-
tion image.
P dstid[4] n[2] wind[4] ignore[2*4] srcid[4] sp[2*4] p0[2*4]
dp[2*2*n]
Draw a filled polygon. The parameters dstid, n, srcid,
sp, p0, and dp are treated in the same way as the poly-
gon line command (`p'). The ignore parameter is
ignored! The wind parameter specifies the winding rule
to use for determining which pixels are `inside' the
polygon. A value of ~0 specifies that pixels are
inside if the polygon's winding number about the point
is non-zero. For the value 1, a pixel is inside if the
winding number is odd. The complements of these values
(0 and ~1) result in outside pixels being painted.
r id[4] R[4*4]
Read the pixel values from the rectangle R of image id.
The binary values are returned by reading the data file
of the client. The data is formatted one horizontal
line at a time, starting with the top-left pixel of R.
The bit-width of the pixel values depends on the ldepth
of the image. Pixel values are packed into bytes most
significant bit first. Each line encodes to a whole
number of bytes in the output, even if the last byte is
not completely filled.
s dstid[4] srcid[4] fontid[4] P[2*4] clipR[4*4] sp[2*4]
ni[2] index[2*ni]
Draw text using font fontid. The text line is drawn
with its top left corner starting at point P in dstid.
The text string, of length ni, is given by index, the
sequence of font character indices. The clipping rect-
angle of dstid is temporarily set to clipR.
Characters are rendered using the associated character
image as a mask. Only those pixels in the srcid image
are copied for which the corresponding pixel in the
character rectangle of the font image is non-zero. The
point sp of the source image is aligned with point P of
dstid.
Page 6 Plan 9 (printed 4/25/24)
DRAW(3) DRAW(3)
S id[4] ldepth[4]
Import public screen id. Before a public screen can be
used by a client that did not create it, its ID must be
imported. The device checks that id is a valid public
screen and that its ldepth matches that specified.
t top[1] nw[2] id[4*n]
Raise (or lower) nw windows to the top (or bottom) of
their screen. All the window IDs given in the id list
must belong to the same screen. If top is non-zero,
the windows are brought in front of any others, the
first window of the list being foremost. Otherwise,
they are pushed to the back, the first window of the
list being placed right at the back.
v Update changes to the display. Drawing on the display
image (id 0) immediately affects the contents of the
internal image but the changes are not automatically
flushed to the physical display hardware. This command
updates the display hardware with the modified region
of the display image.
w id[4] R[4*4] data[1*x]
Write pixel values to the rectangle R in the image
given by id. The pixel data in the data parameter is in
the same format as returned by the read pixels (`r')
command and must be of at least the length required for
the given R and image ldepth.
W id[4] R[4*4] data[1*x]
Write pixel values from compressed data. The parame-
ters are the same as for the 'w' command, except that
the data is in a compressed format. The data is in the
Inferno compressed image format (see image(6)),
stripped of all headers; just the variable-length code
words are given.
SOURCE
/emu/devdraw.c
/os/port/devdraw.c
/memimage/*.c
/memlayer/*.c
SEE ALSO
draw-intro(2), image(6)
Page 7 Plan 9 (printed 4/25/24)