diff options
Diffstat (limited to 'man/2/draw-0intro')
| -rw-r--r-- | man/2/draw-0intro | 268 |
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) |