Introduction to Limbo modules

Although many modules are self-contained, dependencies may exist. For example, the system module, Sys, provides basic services that some other modules require.

A number of minor functions are packaged as individual modules but share a single include file. For example, see /include/lib.m.

The manual pages describe in their synopsis sections how to include a module definition during compilation and load an implementation during execution. The synopsis sections also list the functions, abstract data types, and constants that are discussed in the following Description sections. Although the include files declare these components, the manual pages list them explicitly. In all cases, the enclosing module declaration is assumed so that unqualified identifiers can be used in the text without ambiguity.

Some modules are described in a single page, such as regex. Larger modules are divided into several related pages, such as Limbo Math Modules, elem, fp, and linalg.

Synopsis

include "sys.m";
sys:= load Sys Sys->PATH;
include "draw.m";
draw:= load Draw Draw->PATH;
include "tk.m";
tk:= load Tk Tk->PATH;
... etc.
Generically
include "module.m";
mod:= load Module Module ->PATH;

Draw Modules

context	graphics environment
display	connection to draw device
font	character images for Unicode text
image	pictures and drawing
point	coordinate position
pointer	state of a pointer device such as a mouse
rectangle	rectangular portion of the plane
screen	type to define the abstract data structures for the windows on a display, or subwindows within a window

include "draw.m";
draw:=  load Draw Draw->PATH;

Pixels

When an image is displayed, the value of each pixel determines the color of the display. For color displays, Inferno uses a fixed color map for each display depth (see rgbv) and the application is responsible for mapping its desired colors to the values available. Facilities exist to convert from (red, green, blue) triplets to pixel values.

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 coordinates 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 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 image.
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 image), 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 primitive on the underlying images, Fonts provide 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 font, utf, and font.
Context	A Context provides an interface to the system graphics and interactive devices. The system creates this context when it starts an application.
Pointer	The Pointer type conveys information for pointing devices, such as mice or trackballs.

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 boolean Image.repl causes the image to behave as if replicated across the entire integer plane, thus tiling the destination 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 disjoint from Image.r. See image 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 created 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. In Limbo, one can eliminate references by assigning nil to reference variables, returning from functions whose local variables hold references, etc.

Return Values

See Also