DRAW-INTRO(2) DRAW-INTRO(2)
NAME
draw - basic graphics facilities module
SYNOPSIS
include "draw.m";
draw := load Draw Draw->PATH;
setalpha: fn(rgba: int, alpha: int): int;
DESCRIPTION
Inferno's Draw module provides basic graphics facilities,
defining drawing contexts, images, character fonts, and
rectangular geometric operations. See wmlib(2) and tk(2)
for higher level operations, such as windows and menu han-
dling.
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 between 1 and 32 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. Images have one
or more channels: colour channels, greyscale channels,
colour map indices, and others, as described in colour(6).
Each pixel value contains a component of each such channel.
All pixels in an image have the same size, or depth, and the
same component structure.
When an image is displayed, the value of each pixel deter-
mines the colour of the display, according to the interpre-
tation of the image's channels. For instance, on `true
colour' displays, the display image might contain red, blue
and green colour channels, and each pixel value will have
red, blue and green colour components. For displays with
only 8 bits per pixel or less, Inferno uses a fixed colour
map for each display depth (see colour(6)). Facilities exist
in draw-display(2) to convert between (red, green, blue)
triplets and colour-mapped pixel values, but the mapping is
often done automatically by the graphics operations when
images with different channel structures are combined.
Draw uses a standard representation of colour constants in
calls to create coloured images or to initialise new images
with a given colour. This is referred to as `32-bit RGBA
format'. Each constant colour is represented as a 32-bit
integer, with 8-bit red, blue and green colour components,
and an 8-bit alpha component, in that order from most to
least significant byte.
Page 1 Plan 9 (printed 12/22/24)
DRAW-INTRO(2) DRAW-INTRO(2)
The RGB values in a colour are premultiplied by the alpha
value; for example, a 50% red is int 16r7F00007F not int
16rFF00007F. The function Draw->setalpha performs the alpha
computation on a given colour rgba in 32-bit RGBA format,
ignoring its initial alpha value, and returning the result
of multiplying each colour component by the supplied alpha.
For example, to make a 50% red color value, one could exe-
cute draw->setalpha(Draw->Red, 16r7F).
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)
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
Page 2 Plan 9 (printed 12/22/24)
DRAW-INTRO(2) DRAW-INTRO(2)
convenient 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 structure of an Image is stored as Chans value
Image.chans; the image's pixel depth in bits is stored as
integer Image.depth.
An image may be marked for replication: when set, the
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
Page 3 Plan 9 (printed 12/22/24)
DRAW-INTRO(2) DRAW-INTRO(2)
interrogated (such as by the %r format (see sys-print(2)))
for more information.
SOURCE
/libinterp/draw.c
/libdraw/*.c
SEE ALSO
draw(3), ir(2), prefab-intro(2), tk(2), wmlib(2), colour(6),
font(6), image(6)
Page 4 Plan 9 (printed 12/22/24)