DRAW-INTRO(2) DRAW-INTRO(2)
NAME
draw - basic graphics facilities module
SYNOPSIS
include "draw.m";
draw := load Draw Draw->PATH;
DESCRIPTION
Inferno's Draw module provides basic graphics facilities,
defining drawing contexts, images, character fonts, and
rectangular geometric operations. See prefab-intro(2) and
tk(2) for higher level operations, such as windows and menu
handling.
Pixels
Images are defined on a rectangular region of an integer
plane with a picture element, or pixel, at each grid point.
Pixel values are integers with 0, 1, 2, 4, or 8 bits per
pixel, and all pixels in a given image have the same size,
or depth. Some operations allow images with different depths
to be combined, for example to do masking.
When an image is displayed, the value of each pixel deter-
mines the colour of the display. For colour displays,
Inferno uses a fixed colour map for each display depth (see
rgbv(6)) and the application is responsible for mapping its
desired colours to the values available. Facilities exist
to convert from (red, green, blue) triplets to pixel values.
Note that the triplet (255, 255, 255) maps to a pixel with
all bits zero.
Terminology
Point The graphics plane is defined on an integer grid,
with each (x, y) coordinate identifying the upper
left corner of the corresponding pixel. The
plane's origin, (0, 0), resides at the upper left
corner of the screen; x and y coordinates increase
to the right and down. The abstract data type,
Point defines a coordinate position.
Rect The type Rect defines a rectangular region of the
plane. It comprises two Points, min and max, and
specifies the region defined by pixels with coordi-
nates greater than or equal to min and strictly
less than max, in both x and y. This half-open
property allows rectangles that share an edge to
have equal coordinates on the edge.
Display The type Display represents a physical display,
corresponding to a single connection to a draw(3)
Page 1 Plan 9 (printed 12/30/24)
DRAW-INTRO(2) DRAW-INTRO(2)
device. Besides the image of the display itself,
the Display type also stores references to off-
screen images, fonts, and so on. The contents of
such images are stored in the display device, not
in the client of the display, which affects how
they are allocated and used, see for example draw-
image(2).
Screen The Screen type is used to manage a set of windows
on an image, typically but not necessarily that of
a display. Screens and hence windows may be built
recursively upon windows for subwindowing or even
on off-screen images.
Image The Image type provides basic operations on groups
of pixels. Through a few simple operations, most
importantly the draw image combination operator
(see draw-image(2)), the Image type provides the
building blocks for Display, Screen, and Font.
Font A Font defines which character image to draw for
each character code value. Although all character
drawing operations ultimately use the draw primi-
tive on the underlying images, Fonts provide conve-
nient and efficient management of display text.
Inferno uses the 16-bit Unicode character encoding,
so Fonts are managed hierarchically to control
their size and to make common subsets such as ASCII
or Greek efficient in practice. See draw-font(2),
utf(6), and font(6).
Context A Context provides an interface to the system
graphics and interactive devices. The system cre-
ates this context when it starts an application.
Pointer The Pointer type conveys information for pointing
devices, such as mice or trackballs.
More about Images
An image occupies a rectangle, Image.r, of the graphics
plane. A second rectangle, Image.clipr, defines a clipping
region for the image. Typically, the clipping rectangle is
the same as the basic image, but they may differ. For exam-
ple, the clipping region may be made smaller and centered on
the basic image to define a protected border.
The pixel depth of an Image is stored as a logarithm called
Image.ldepth; pixels with 1, 2, 4, and 8 bits correspond to
ldepth values 0, 1, 2, and 3. In future, other image depths
may be supported.
An image may be marked for replication: when set, the
Page 2 Plan 9 (printed 12/30/24)
DRAW-INTRO(2) DRAW-INTRO(2)
boolean Image.repl causes the image to behave as if repli-
cated across the entire integer plane, thus tiling the des-
tination graphics area with copies of the source image.
When replication is turned on, the clipping rectangle limits
the extent of the replication and may even usefully be dis-
joint from Image.r. See draw-image(2) for examples.
The Image member functions provide facilities for drawing
text and geometric objects, manipulating windows, and so on.
Objects of type Display, Font, Screen, and Image must be
allocated by the member functions; if such objects are cre-
ated with a regular Limbo definition, they will not behave
properly and may generate run-time errors.
There are no ``free'' routines for graphics objects.
Instead Limbo's garbage collection frees them automatically.
As is generally so within Limbo, one can eliminate refer-
ences by assigning nil to reference variables, returning
from functions whose local variables hold references, etc.
RETURN VALUES
Most drawing operations operate asynchronously, so they have
no error return. Functions that allocate objects return nil
for failure; in such cases the system error string may be
interrogated (such as by the %r format (see sys-print(2)))
for more information.
SOURCE
/interp/draw.c
/image/*.c
SEE ALSO
draw(3), ir(2), prefab-intro(2), tk(2), font(6), image(6)
Page 3 Plan 9 (printed 12/30/24)