DRAW(3)DRAW(3)

NAME

draw – screen graphics

SYNOPSIS

bind -a #i /dev

/dev/draw/new

/dev/draw/n/ctl /dev/draw/n/data /dev/draw/n/colormap /dev/draw/n/refresh

#include <u.h> #include <draw.h>

ushort BGSHORT(uchar *p) ulong BGLONG(uchar *p) void BPSHORT(uchar *p, ushort v) void BPLONG(uchar *p, ulong v)

DESCRIPTION

The draw device serves a three-level file system providing an interface to the graphics facilities of the system. Each client of the device connects by opening /dev/draw/new and reading 12 strings, each 11 characters wide followed by a blank: the connection number (n), the image id (q.v.) of the display image (always zero), the channel format of the image, the replicate bit, the min.x, min.y, max.x, and max.y of the display image, and the min.x, min.y, max.x, and max.y of the clipping rectangle. The channel format string is described in image(6), and the other fields are decimal numbers.

The client can then open the directory /dev/draw/n/ to access the ctl, data, colormap, and refresh files associated with the connection.

Via the ctl and data files, the draw device provides access to images and font caches in its private storage, as described in graphics(2). Each image is identified by a 4-byte integer, its id.

Reading the ctl file yields 12 strings formatted as in /dev/draw/new, but for the current image rather than the display image. The current image may be set by writing a binary image id to the ctl file.

A process can write messages to data to allocate and free images, fonts, and subfonts; read or write portions of the images; and draw line segments and character strings in the images. All graphics requests are clipped to their images. Some messages return a response to be recovered by reading the data file.

The format of messages written to data is a single letter followed by binary parameters; multibyte integers are transmitted with the low order byte first. The BPSHORT and BPLONG macros place correctly formatted two- and four-byte integers into a character buffer. BGSHORT and BGLONG retrieve values from a character buffer. Points are two four-byte numbers: x, y. Rectangles are four four-byte numbers: min x, min y, max x, and max y. Images, screens, and fonts have 32-bit identifiers. In the discussion of the protocol below, the distinction between identifier and actual image, screen, or font is not made, so that “the object id should be interpreted as “the object with identifier id”. The definitions of constants used in the description below can be found in draw.h.

The following requests are accepted by the data file. The numbers in brackets give the length in bytes of the parameters.

unhandled troff command .HP

A id[4] imageid[4] fillid[4] public[1]
Allocate a new Screen (see window(2)) with screen identifier id using backing store image imageid, filling it initially with data from image fillid. If the public byte is non-zero, the screen can be accessed from other processes using the publicscreen interface.

unhandled troff command .HP

b id[4] screenid[4] refresh[1] chan[4] repl[1] r[4*4] clipr[4*4] color[4]
Allocate an image with a given id on the screen named by screenid. The image will have rectangle r and clipping rectangle clipr. If repl is non-zero, the image’s replicate bit will be set (see draw(2)).

Refresh specifies the method to be used to draw the window when it is uncovered. Refbackup causes the server to maintain a backing store, Refnone does not refresh the image, and Refmesg causes a message to be sent via the refresh file (q.v.).  

The image format is described by chan, a binary version of the channel format string. Specifically, the image format is the catenation of up to four 8-bit numbers, each describing a particular image channel. Each of these 8-bit numbers contains a channel type in its high nibble and a bit count in its low nibble. The channel type is one of CRed, CGreen, CBlue, CGrey, CAlpha, CMap, and CIgnore. See image(6).  

Color is the catenation of four 8-bit numbers specifying the red, green, blue, and alpha channels of the color that the new image should be initially filled with. The red channel is in the highest 8 bits, and the alpha in the lowest. Note that color is always in this format, independent of the image format.  

unhandled troff command .HP

c dstid[4] repl[1] clipr[4*4]
Change the replicate bit and clipping rectangle of the image dstid. This overrides whatever settings were specified in the allocate message.

unhandled troff command .HP

d dstid[4] srcid[4] maskid[4] dstr[4*4] srcp[2*4] maskp[2*4]
Use the draw operator to combine the rectangle dstr of image dstid with a rectangle of image srcid, using a rectangle of image maskid as an alpha mask to further control blending. The three rectangles are congruent and aligned such that the upper left corner dstr in image dstid corresponds to the point srcp in image srcid and the point maskp in image maskid. See draw(2).

unhandled troff command .HP

D debugon[1]
If debugon is non-zero, enable debugging output. If zero, disable it. The meaning of “debugging output” is implementation dependent.

unhandled troff command .HP

e dstid[4] srcid[4] c[2*4] a[4] b[4] thick[4] sp[2*4] alpha[4] phi[4]
Draw an ellipse in image dst centered on the point c with horizontal and vertical semiaxes a and b. The ellipse is drawn using the image src, with the point sp in src aligned with c in dst. The ellipse is drawn with thickness 1+2×thick.

If the high bit of alpha is set, only the arc of the ellipse from degree angles alpha to phi is drawn. For the purposes of drawing the arc, alpha is treated as a signed 31-bit number by ignoring its high bit.  

unhandled troff command .HP

E dstid[4] srcid[4] center[2*4] a[4] b[4] thick[4] sp[2*4] alpha[4] phi[4]
Draws an ellipse or arc as the e message, but rather than outlining it, fills the corresponding sector using the image srcid. The thick field is ignored, but must be non-negative.

unhandled troff command .HP

f id[4]
Free the resources associated with the image id.

unhandled troff command .HP

F id[4]
Free the screen with the specified id. Windows on the screen must be freed separately.

unhandled troff command .HP

i id[4] n[4] ascent[1]
Treat the image id as a font cache of n character cells, each with ascent ascent.

unhandled troff command .HP

l cacheid[4] srcid[4] index[2] r[4*4] sp[2*4] left[1] width[1]
Load a character into the font cache associated with image cacheid at cache position index. The character data is drawn in rectangle r of the font cache image and is fetched from the congruent rectangle in image srcid with upper left corner sp. Width specifies the width of the characterthe spacing from this character to the nextwhile left specifies the horizontal distance from the left side of the character to the left side of the cache image. The dimensions of the image of the character are defined by r.

unhandled troff command .HP

L dstid[4] p0[2*4] p1[2*4] end0[4] end1[4] thick[4] srcid[4] sp[2*4]
Draw a line of thickness 1+2×thick in image dstid from point p0 to p1. The line is drawn using the image srcid, translated so that point sp in srcid aligns with p0 in dstid. The end0 and end1 fields specify whether the corresponding line end should be a square, a disc, or an arrow head. See line in draw(2) for more details.

unhandled troff command .HP

N id[4] in[1] j[1] name[j]
If in is non-zero, associate the image id with the string name. If in is zero and name already corresponds to the image id, the association is deleted.

unhandled troff command .HP

n id[4] j[1] name[j]
Introduce the identifier id to correspond to the image named by the string name.

unhandled troff command .HP

o id[4] r.min[2*4] scr[2*4]
Position the window (layer) id so that its upper left corner is at the point scr on its screen. Simultaneously change its internal (logical) coordinate system so that the point r.min corresponds to the upper left corner of the window, see memlorigin(2).

unhandled troff command .HP

O op[1]
Set the compositing operator to op for the next draw operation. (The default is SoverD).

unhandled troff command .HP

p dstid[4] n[2] end0[4] end1[4] thick[4] srcid[4] sp[2*4] dp[2*2*(n+1)]
Draw a polygon of thickness 1+2×thick. It is conceptually equivalent to a series of n line-drawing messages (see L above) joining adjacent points in the list of points dp. The source image srcid is translated so that the point sp in srcid aligns with the first point in the list dp. The polygon need not be closed: end0 and end1 specify the line endings for the first and last point on the polygon. All interior lines have rounded ends to make smooth joins.

unhandled troff command .HP

P dstid[4] n[2] wind[4] ignore[2*4] srcid[4] sp[2*4] dp[2*2*(n+1)]
Draw a polygon as the p message, but fill it rather than outlining it. 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 meaning of other values is undefined. The polygon is closed with a line if necessary.

unhandled troff command .HP

r id[4] r[4*4]
Cause the next read of the data file to return the image pixel data corresponding to the rectangle r in image id.

unhandled troff command .HP

s dstid[4] srcid[4] fontid[4] dp[2*4] clipr[4*4] sp[2*4] n[2] n*(index[2])
Draw in the image dstid the text string specified by the n cache indices into font fontid, starting with the upper left corner at point p in image dstid. The image drawn is taken from image srcid, translated to align sp in srcid with dp in dstid. All drawing is confined to the clipping rectangle clipr in dstid.

unhandled troff command .HP

x dstid[4] srcid[4] fontid[4] dp[2*4] clipr[4*4] sp[2*4] n[2] bgid[4] bp[2*4] n*(index[2])
Like the string drawing s command, but fill the background of each character with pixels from image bgid. The image bgid is translated so that the point bp aligns with the point dp in dstid.

unhandled troff command .HP

S id[4] chan[4] Attach to the public screen with the specified id. It is an error if the screen does not exist, is not public, or does not have the channel descriptor chan for its associated image.

unhandled troff command .HP

t top[1] n[2] n*id[4]
Send n windows to the top (if t is non-zero) or bottom (if t is zero) of the window stack. The window is specified by the list of n image ids are moved as a group, maintaining their own order within the stack.

unhandled troff command .HP

v
Flush changes from a soft screen, if any, to the display buffer.

unhandled troff command .HP

y id[4] r[4*4] buf[x*1]

unhandled troff command .ti

Y id[4] r[4*4] buf[x*1]
Replace the rectangle r of pixels in image id with the pixel data in buf. The pixel data must be in the format dictated by id’s image channel descriptor (see image(6)). The y message uses uncompressed data, while the Y message uses compressed data. In either case, it is an error to include more data than necessary.

Reading the colormap returns the system color map used on 8-bit displays. Each color map entry consists of a single line containing four space-separated decimal strings. The first is an index into the map, and the remaining three are the red, green, and blue values associated with that index. The color map can be changed by writing entries in the above format to the colormap file. Note that changing the system color map does not change the color map used for calculations involving m8 images, which is immutable.

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.

SOURCE

/sys/src/9/port/devdraw.c
/sys/src/libmemdraw

DIAGNOSTICS

Most messages to draw can return errors; these can be detected by a system call error on the write(see read(2)) of the data containing the erroneous message. The most common error is a failure to allocate because of insufficient free resources. Most other errors occur only when the protocol is mishandled by the application. Errstr(2) will report details.

BUGS

The Refmesg refresh method is not fully implemented.
The colormap files only reference the system color map, and as such should be called /dev/colormap rather than /dev/draw/n/colormap.