Since the Draw module provides primitive graphics, its functions and data are at a lower level than is typical of a graphics API. Hence, there are some concepts and terms that would be helpful to introduce first.
Context
argument holds the references of the graphics resources.
Two important elements of Context
are the display
and screen
types.
display
of type ref Draw->Display
represents a physical display, corresponding to a single connection to a draw device (/dev/draw
). 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.
Objects of type Display
must be allocated by its member functions. If a Display
object is created with a regular Limbo definition, it will not behave properly and may generate run-time errors.
screen
of type ref Draw->Screen
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.
Objects of type Screen
must be allocated by its member functions. If a Screen
object is created with a regular Limbo definition, it will not behave properly and may generate run-time errors.
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, and the application is responsible for mapping its desired colors to the values available. There are functions to convert from red, green, blue triplets to pixel values.
Point
defines a coordinate position. 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.
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.
Image
provides basic operations on groups of pixels. Through a few simple operations, the Image
type provides the building blocks for Display
, Screen
, and Font
. Objects of type Image
must be allocated by its member functions. If an Image
object is created with a regular Limbo definition, it will not behave properly and may generate run-time errors.
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 example, 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.
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
.
The Image
member functions provide facilities for drawing text and geometric objects, manipulating windows, and so on.
Font
type 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 the 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.
Objects of type Font
must be allocated by its member functions. If a Font
object is created with a regular Limbo definition, it will not behave properly and may generate run-time errors.
Pointer
type conveys information for pointing devices, such as mice or trackballs.
nil
for failure. In such cases the system error string may be interrogated (such as by the %r print format) for more information.
nil
to reference variables, returning from functions whose local variables hold references, and so on.