20060303-partial

1 files changed, 268 insertions, 0 deletions

diff --git a/man/2/draw-0intro b/man/2/draw-0intro
new file mode 100644
index 00000000..6fb4384a
--- /dev/null
+++ b/man/2/draw-0intro
@@ -0,0 +1,268 @@
+.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)