code: 9ferno

ref: 728eff896074bfa69130c243941ffc6d5c19a735
dir: /man/2/draw-0intro/

View raw version
.TH DRAW-INTRO 2
.SH NAME
draw \- basic graphics facilities module
.SH SYNOPSIS
.EX
include "draw.m";
draw := load Draw Draw->PATH;

setalpha:  fn(rgba: int, alpha: int): int;
.EE
.SH DESCRIPTION
Inferno's
.B Draw
module provides basic graphics facilities, defining drawing
contexts, images, character fonts, and rectangular geometric operations.
See
.IR wmlib (2)
and
.IR tk (2)
for higher level operations, such as windows and menu handling.
.SS Pixels
Images are defined on a rectangular region of
an integer plane with a picture element, or
.IR 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
.IR 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
.IR colour (6).
Each pixel value contains a component of each such channel.
All pixels in an image have the same size, or
.IR depth ,
and the same component structure.
.PP
When an image is displayed, the value of each pixel determines the colour
of the display, according to the interpretation 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
.IR colour (6)).
Facilities exist in
.IR 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.
.PP
.B 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.
.PP
The RGB values in a colour are
.I premultiplied
by the alpha value; for example, a 50% red is
.B "int 16r7F00007F"
not
.BR "int 16rFF00007F" .
The function
.B Draw->setalpha
performs the alpha computation on a given colour
.I rgba
in 32-bit RGBA format,
ignoring its initial alpha value, and returning the
result of multiplying each colour component by the supplied
.BR alpha .
For example, to make a 50% red color value, one could execute
.B draw->setalpha(Draw->Red,
.BR 16r7F) .
.SS Terminology
.TF Pointer
.PD
.TP
.B Point
The graphics plane is defined on an integer grid,
with each
.RI ( 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;
.I x
and
.I y
coordinates increase to the right and down.
The abstract data type,
.BR Point
defines a coordinate position.
.TP
.B Rect
The type
.B Rect
defines a rectangular region of the plane.
It comprises two
.BR Points ,
.B min
and
.BR max ,
and specifies the region defined by pixels with coordinates
greater than or equal to
.B min
and strictly less than
.BR max ,
in both
.I x
and
.IR y .
This
.I half-open
property allows rectangles that share an edge to have equal coordinates on the edge.
.TP
.B Display
The type
.B Display
represents a physical display, corresponding to a single connection to a
.IR draw (3)
device.
Besides the image of the display itself, the
.B 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
.IR draw-image (2).
.TP
.B Screen
The
.B Screen
type is used to manage a set of windows on an image, typically but not necessarily
that of a display.
.B Screens
and hence windows may be built recursively upon windows for
subwindowing or even on off-screen images.
.TP
.B Image
The
.B Image
type provides basic operations on groups of pixels.
Through a few simple operations, most importantly the
.B draw
image combination operator
(see
.IR draw-image (2)),
the
.B Image
type provides the building blocks for
.BR Display ,
.BR Screen ,
and
.BR Font .
.TP
.B Font
A
.B Font
defines which character image to draw for each character code value.
Although all character drawing operations ultimately use the
.B draw
primitive on the underlying images,
.B Fonts
provide convenient and efficient management of display text.
Inferno uses the 16-bit Unicode character encoding, so
.B Fonts
are managed hierarchically to control their size and to make
common subsets such as ASCII or Greek efficient in practice.
See
.IR draw-font (2),
.IR utf (6),
and
.IR font (6).
.TP
.B Context
A
.B Context
provides an interface to the system graphics and interactive devices.
The system creates this context when it starts an application.
.TP
.B Pointer
The
.B Pointer
type conveys information for pointing devices, such as mice or trackballs.
.SS More about Images
.PP
An image occupies a rectangle,
.BR Image.r ,
of the graphics plane.
A second rectangle,
.BR 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.
.PP
The pixel structure of an
.B Image
is stored as
.B Chans
value
.BR Image.chans ;
the image's pixel depth in bits is stored as integer
.BR Image.depth .
.PP
An image may be marked for replication: when set, the boolean
.B 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
.BR Image.r .
See
.IR draw-image (2)
for examples.
.PP
The
.B Image
member functions provide facilities for drawing text and geometric objects,
manipulating windows, and so on.
.PP
Objects of type
.BR Display ,
.BR Font ,
.BR Screen ,
and
.B 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.
.PP
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 references by assigning
.B nil
to reference variables, returning from functions
whose local variables hold references, etc.
.SH RETURN VALUES
Most drawing operations operate asynchronously, so they have
no error return.
Functions that allocate objects return
.B nil
for failure; in such cases the system error string may be
interrogated (such as by the
.B %r
format (see
.IR sys-print (2))) 
for more information.
.SH SOURCE
.B /libinterp/draw.c
.br
.B /libdraw/*.c
.SH SEE ALSO
.IR draw (3),
.IR ir (2),
.IR prefab-intro (2),
.IR tk (2),
.IR wmlib (2),
.IR colour (6),
.IR font (6),
.IR image (6)