NAME

Display − connection to draw device

SYNOPSIS

include"draw.m";
draw := load Draw Draw->PATH;
 Display: adt
{
    image:       ref Image;
    ones:        ref Image;
    zeros:       ref Image;
     allocate:    fn(dev: string):
                 ref Display;
    startrefresh:fn(d: self ref Display);
    publicscreen:fn(d: self ref Display, id: int):
                 ref Screen;
    newimage:    fn(d: self ref Display,
                 r: Rect, ldepth, repl, color: int):
                 ref Image;
    color:       fn(d: self ref Display, color: int):
                 ref Image;
    rgb:         fn(d: self ref Display, red, green, blue: int):
                 ref Image;
    open:        fn(d: self ref Display, name: string):
                 ref Image;
    readimage:   fn(d: self ref Display, fd: ref Sys->FD):
                 ref Image;
    writeimage:  fn(d: self ref Display, fd: ref Sys->FD,
                 i: ref Image): int;
    rgb2cmap:    fn(d: self ref Display, red, green, blue: int):
                 int;
    cmap2rgb:    fn(d: self ref Display, color: int):
                 (int, int, int);
    cursor:      fn(d: self ref Display, i: ref Image, p: ref Point):
                 int;
    cursorset:   fn(d: self ref Display, p : Point);
};

DESCRIPTION

The ­Display type represents a connection to a draw(3) device. This device is the external representation of a physical display, such as a CRT, and its associated memory. It contains the storage for all images, even invisible ones, so all ­Image objects must be allocated through ­Display member functions.  Graphics operations that use multiple ­Image objects may not mix images from different Displays. 

­image The visible contents of the display; draw on ­image to change the display. 

ones, zeros
Replicated images of a single pixel, either all ones (true, black) or all zeros (false, white). Useful as masks for basic graphical operations.

allocate(dev)
Attach to a new display, represented by the draw(3) device mounted in the specified ­dev directory.  If ­dev is the empty string, ­/dev is used.  The return value is ­nil if the allocation fails. 

d.startrefresh()
After allocating a ­Display object, the application should spawn a process to call startrefresh; this thread will receive and process window refresh events from the device. 

d.publicscreen(id)
Create a locally addressable pointer to a public Screen; see display-screen(2). 

d.newimage(r, ldepth, repl, color)
Allocate an off-screen Image.  The arguments supply values for the Image’s r, ldepth, and repl, and an initial color map index, used to paint the image when created.  The image’s ­clipr is initialized to r. 

d.color(color)
Creates a single-pixel, replicated off-screen image of the specified colour. The ­Draw module defines constants for several common colours: Draw−>Black, Draw−>Blue, Draw−>Green, Draw−>Red, Draw−>White, and Draw−>Yellow. 

d.rgb(red, green, blue)
Uses the values (from 0 (off) through 255 (full on)) of red, green, and blue to find the closest matching colour map entry, and create a single-pixel replicated image of that colour. Equivalent to d.color(d.rgb2cmap( r, g, b)). 

d.open(name)
Read an image description from the named file and return an ­Image holding the picture.  See image(6) for more information about image files.

d.readimage(fd)
Analogous to open, but from an open file descriptor rather than a named file. 

d.writeimage(fd, i)
Complement of readimage: write an image file representing ­i to the open file descriptor. 

d.rgb2cmap(red, green, blue)
Return the colour map index of the colour that best matches the colour triple.  The values of the components range from 0 (no colour) to 255 (saturated).

d.cmap2rgb(color)
Decompose the colour into a colour triple and return the result.

d.cursor(i, p)
Set the current cursor. If ­i is the image of the current display, then the graphics cursor will be set to its default value, otherwise ­i must be an image with ldepth 0 and the following rules apply: the size of the cursor will be half the horizontal height of ­i (subject to system-dependent restrictions on cursor size). The top half and the bottom half of the image are treated as two independent masks. When the cursor is drawn, pixels congruent with non-zero bits in the top half are cleared and then pixels congruent with non-zero bits in the bottom half are set.  ­P gives the offset added to the mouse position when drawing the cursor image. 

d.cursorset(p)
Set the position of the mouse cursor to p.

BUGS

The interface to ­cursor does not allow the use of colour mouse cursors, even on systems that allow them. The interface is likely to change in this respect. 

Plan 9  —  June 29, 2000