
        Copyright (C) 1993-95, Alex Iakovlev & Dimon Maslov





          GRAPHICS SUPPORT LIBRARY FOR MODULA-2 LANGUAGE

                           MultiGraph-2


                         Library Overview







                              Moscow
                               1995



                             CONTENTS

    Introduction .......................................
    Chapter 1. Architecture ............................
    Chapter 2. Basic level .............................
    Chapter 3. Screen level ............................
    Chapter 4. Window level ............................
    Chapter 5. Dialogue level ..........................
    Chapter 6. Library sources .........................


INTRODUCTION


Graphics library MultiGraph-2 supports the window-style graphics
interface for programs written in Modula-2 language. There are
three shareware versions of the library for three popular Modula-2
compilers, working under operating system MS-DOS on IBM PC XT/AT
and compatibles computers.

TopSpeed Modula-2 compiler was developed by Jensen & Partners
International (JPI) in 1986-1989 and is widely used by computer
science students and professionals in many countries now. The
version 1.17 of this compiler is informally called Turbo-Modula.
MultiGraph-2 library for this compiler was the first shareware
version of the library. The line of compilers under the TopSpeed
trade mark is now supported by Clarion Software Inc. This firm
supplies now the version 3.10 of TopSpeed compiler's package.
Multiraph-2 library for this version of TopSpeed Modula-2 is
supplied as shareware from March 1994.

Once more remarkable compiler for Modula-2 language was developed
by Stony Brook Software. MultiGraph-2 library for the version 2.2
of this compiler is supplied as shareware from March 1994 too.

The library in source form may be supplied to registered users
only. The registration is explained in the file REGISTER.TXT. See
the Chapter 6 of this overview to understand the profits of
receiving the library in the source form.


Chapter 1. ARCHITECTURE


The library consists of four levels - basic, screen, window and
dialogue levels.

The basic level contains some service modules, geometric modules,
a number of driver modules, error status module and some
configuration modules.

The screen level contains the screen manager and general primitives
of graphics input and output. The property of the library is the
convenient support of graphics input, owing to the careful
development of graphics input technology. In particular, the
procedures driving graphics cursors are developed. Screen level
is based on geometric module and driver modules.

The basic module on the screen level is the screen manager "Scr",
which supports the most of standard graphics modes for EGA and VGA
adapters, some of modified graphics modes for VGA adapter as well
as a number of high- and true-color resolution modes on
VESA-compatible Super-VGA boards. The screen manager allows to
create the images not only on the screen but also in the memory
on the so-called "pixmaps". Arbitrary quantity of such pixmaps may
be created in the memory, and besides there is an opportunity
to copy the images from one pixmap to another. The screen is
the special case of the pixmap.

The window level contains the module for the window management
called "Win", fulfilling the general window procedures. This module
is the base for the group of modules, containing the window
versions of graphics input/output primitives.

The dialogue level is another group of modules, providing the
creation of interactive interfaces. This level is based on
geometric module, driver modules and screen/window levels.


Chapter 2. BASIC LEVEL


The service sublevel consists of the modules "SrvLex", "SrvSys",
"SrvMat", "SrvObj" and "SrvLow", but their definition modules
aren't supplied. We include the "SrvLex" definition module
only as it is used in the demonstration programs. The others
are used internally and aren't to be learned by users at all.

The geometric sublevel consists of the modules "Geo" and "GeoRgn".
Module "Geo" contains the general geometric types "Point" and
"Rectangle", as well as the procedures, used in the work with the
variables of these types. The module doesn't draw, but only
fulfills geometric calculations. Geometric types, mentioned above,
are used in the most types and procedures of the library on all
its levels. Module "GeoRgn" is the internal module and is used
by the window management module, and its definition module isn't
supplied.

The drivers sublevel creates the procedure layer, independent from
the operating system. This layer permits to hide the peculiarities
of different physical devices from user programs. Some of these
modules are added to the library to simplify its porting only.

The drivers sublevel consists of six modules-drivers, managing
different physical input/output devices:

   DrvKbd  - buffered keyboard
   DrvMem  - memory manager
   DrvMou  - mouse in relative coordinates
   DrvSnd  - sound
   DrvClk  - system clock
   DrvDsk  - disk files

MODULE DrvKbd 

Module-driver "DrvKbd" extends the standard features of keyboard
control. Module has the cyclic buffer. Its size is great enough to
hold the receiving key codes. This module exports the procedures,
permitting to work with this buffer, i.e. to clear it, to write
"artificial" codes in it, to move the current position in the
buffer, etc. Key codes are two bytes. Low byte is able to contain
either character code in ASCII standard or some standard code
(usually zero). High byte is able to contain either zero or
keyboard key number. The module exports the constants,
corresponding to the all control keys.

MODULE DrvMem 

Module-driver "DrvMem" contains standardized procedures to control
the heap memory.

MODULE DrvMou 

Module-driver "DrvMou" creates compact and operating system
independent interface with the mouse. The main procedure
"DrvMou.Get" reads the buttons state and mouse coordinate
displacement. The module doesn't support any graphics cursors. This
may be fulfilled by another means (for example, by primitives of
screen level module "ScrCur").

MODULE DrvSnd 

Module-driver "DrvSnd" support the flexible work with standard
IBM/PC speaker. Module exports the procedure "DrvSnd.Beep",
providing wide opportunities to control the noise, as well as a
number of procedures, generating the standard noises by access to
"DrvSnd.Beep" procedure.

MODULE DrvClk 

Simple module-driver "DrvClk" supports system clock reading and
delay and is useful in demonstration programs.

MODULE DrvDsk 

Simple module-driver "DrvDsk" manages DOS file system via its
system calls. This module is used only in screen fonts control
module, and in demonstration programs too. It was added to the
library to simplify its porting.


Chapter 3. SCREEN LEVEL


Screen level contains the general primitives of graphics input and
output. Since this level is based on the drivers level, its
primitives are also able to draw both on the screen and on the
memory-based pixel maps.

MODULE Scr 

Graphics screen management module "Scr" is the intellectual module,
containing all the necessary functions to be used in the work with
the screen in graphics mode. The table of graphics modes, supported
by the module "Scr" is given below.

        Ŀ
         Resolution    Colors     Adapter      BIOS Mode 
        Ĵ
          320 x 200      16         EGA           0DH    
          640 x 200      16         EGA           0EH    
          640 x 350      16         EGA           10H    
          640 x 480      16         VGA           12H    
          320 x 200     256         VGA           13H    
          320 x 400     256         VGA            -     
          376 x 348     256         VGA            -     
          800 x 600      16      Super-VGA       102H    
          640 x 400     256      Super-VGA       100H    
          640 x 480     256      Super-VGA       101H    
          800 x 600     256      Super-VGA       103H    
         1024 x 768     256      Super-VGA       105H    
         1280 x 1024    256      Super-VGA       107H    
          320 x 200     32K      Super-VGA       10DH    
          640 x 480     32K      Super-VGA       110H    
          800 x 600     32K      Super-VGA       113H    
         1024 x 768     32K      Super-VGA       116H    
          320 x 200     64K      Super-VGA       10EH    
          640 x 480     64K      Super-VGA       111H    
          800 x 600     64K      Super-VGA       114H    
         1024 x 768     64K      Super-VGA       117H    
          320 x 200     16M      Super-VGA       10FH    
          640 x 480     16M      Super-VGA       112H    
          800 x 600     16M      Super-VGA       115H    
        

All the Super-VGA graphics modes work via VESA BIOS Extensions
interface, supported by Video Electronics Systems Association and
many companies, supplying Super-VGA video boards. A majority of
modern video boards have such an interface in their hardware. Some
old boards haven't VESA interface in hardware, but these boards
are usually accompanied with Driver's Disk, which contains a
resident program implementing this interface in software. Another
way is to use universal resident program, which implements VESA
BIOS Extensions for a number of popular graphics boards. One such
a program is written by Kendall Bennet (kjb@citri.edu.au) from
SciTech Software and can be received from a number of hosts,
including GARBO and SIMTEL20.

The module contains the following control procedures:
initialization and termination procedures, viewport control
procedures, palette control procedures, direct color procedures,
and page control procedures.

Graphics mode can be set with the aid of "Scr.SetMode" procedure.
It's necessary to call this procedure before any other call to
the procedures in this module, as it initializes a lot of
procedure variables, used by all the other levels. If you plan to
use only single graphics mode, you may use corresponding
parameterless mode setting procedure - this might decrease the size
of executables due to smart linkage.

In 16-color and 256-color modes programs work with colors according
to their cardinal numbers, which are treated as indices into so
called "palette". The palette is the table, in which the
correspondence between color numbers and its (r,g,b)-components
is established. The module contains two types of palette control
procedures - individual and group. All the individual procedures
control the individual hues of pure colors, corresponding to the
individual color numbers. Group procedures permit to change the
palette as a whole. The procedure mentioned are valid only with
the number of hues and palettes to be more than one. Different
graphics modes correspond to different values of these parameters.

High and true-color modes have no palettes, so these modes are
usually called "direct-color" modes. The module contains some
procedures used to create colors from their (r,g,b)-hues in
direct-color modes. The reverse operations, i.e. color parsing,
are supported too.

By the way, these color creation and parsing procedures can work
in the palette-color modes (with 16/256 collors) too. But in this
case it's necessary to frieze the palette. It can be done with the
aid of the "Scr.SetDirectPaletteShades" procedure.

A graphics adapter is usually able to master several memory pages.
Only one of these pages is visible on the monitor screen. Besides,
the page height may be greater than the screen one. In this case,
there is an opportunity to control the relative position of the
page and the screen, by setting the line number to be on the top
of the screen.

Graphics primitives at this level have a very powerful feature:
they can draw both on the screen and in the memory - on so-called
"pixel maps" (briefly - "pixmaps"). All the drawing, reading and
copying primitives have pixmap parameters which define the
destination (or source) for drawing, reading and copying. The
screen is simply the special pixmap. Any number (in the limits of
the existing memory) of memory-based pixmaps may be created
dynamically during the run time.

Opaque types "Scr.PIXMAP" are used in the work with the pixel
maps. Drawing on the memory-based pixel map is possible even in
the case of the display adapter being in text mode.

Drawing on the pixel maps may be done either with clipping or
without this one. In drawing with clipping all points, being out of
the rectangular viewport, are cut off (i.e. they aren't to be
drawn). In drawing without clipping, all points are to be drawn. On
default, all the drawing is done with clipping, and the clipping
viewport is equal to the surface of the pixel map. Clipping mode is
set in the field "clip", and the viewport - in the field "port" of
the record type "Scr.View".

ATTENTION! Memory-based pixmaps in high and true-color modes may
have large size! Fore example, the pixmap with dimensions 640 x 480
pixels has the following sizes depending upon graphics mode:

   In  16-color modes:    320 x 480 = 153600 bytes
   In 256-color modes:    640 x 480 = 307200 bytes
   In 64K-color modes:   1280 x 480 = 614400 bytes
   In 16M-color modes:   1920 x 480 = 921600 bytes

Therefore, all your heap memory may be exausted by some pixmaps.
We recommend to use extended memory models for applications,
where a lot of memory pixmaps are involved.

Drawing may be done in two modes - copy mode ("Scr.copy") and
xor mode ("Scr.xor"). Xor mode is convenient for graphics cursors.
To set the drawing mode the type "Scr.Function" is used.

The procedures for reading information from pixel maps permit to
determine the point colors on the pixel maps. Now the single
reading procedure is implemented - point color reading.

Copying procedures permit to copy the contents of one pixel map to
another one. These maps may be coincident.

Storing and restoring procedures permit to store the pixel map
content in the memory, and later to restore it. If the pixel map
size exceeds 64 Kbytes, such pixel map may be stored and restored
in parts.

MODULE ScrOut 

The module "ScrOut" exports the attribute type and some output
primitives - zero-dimensional primitives (markers), one-dimensional
primitives (lines), two-dimensional primitives (plane figures,
or areas) and texts.

A number of parameters, defining the primitive form in drawing on
the pixel map, are united in the record with the type "Attrs". The
fields of this record are called "attributes".

Output primitives are constructed in accordance with general rules.
The primitive identifier is chosen so, that one can simply keep it
in mind, since the name reduction is mimimized. Pointer to the
pixel map is always on the first place in the parameter list.
The parameter of type "Attrs" is always on the second place in the
parameter list. Geometric parameters (in screen coordinates), and
other parameters, which are needed for this primitive (for
example, ellipse halfaxes), follow the attributes parameter.

Nowadays the following output primitives are implemented:
markers, straight line segments, polylines, rectangles, ellipses,
polygons, characters and strings. Closed figures may be hollow,
filled by color, or stippled. Stippling is accomplished by
replicating the surface with the rectangle sample. This sample
is defined by its font and its number in this font. If fill
opaque style is chosen, then the module draws the background in
the auxiliary color, and after that performs the stippling.
It's possible to move the origin of stippling with the aid of
corresponding attribute.

Text drawing is treated as a special case of stippling, and
all the stipple attributes are used during the text output.
For example, if you set the fill style attribute equal to
"Scr.fillOpaqueStippled", the string will be drawn as opaque
text with background color.

Output primitives take into account the output viewport and
clipping mode, set on the destination pixel map.

Module "ScrOut" also contains graphics font control procedures.
Opaque type "ScrOut.FONT" is used to control the font. Module
permits to use standard ROM-based fonts. These fonts are numbered
by cardinal numbers. Standard font 0 always exists and has the
character size, dependent upon the display adapter, being
installed. This size may be 8 x 8 pixels (on CGA), 8 x 14 pixels
(on EGA) and 8 x 16 pixels (on VGA). Standard fonts 2 and 3 exist
only when the adapter EGA or VGA is installed, and have their
character sizes 8 x 14 pixels and 8 x 8 pixels accordingly.
Standard font 4 exists only when the adapter VGA is installed, its
character size is 8 x 16 pixels. Except alfanumeric standard fonts
the module supports special standard font 1, consisting of hatching
characters. This font is not complete, i.e. it contains less than
256 characters. The number and the form of characters of this font
will be able to be modified in the next release of the module.

There is an opportunity to create and use nonstandard fonts by
either loading them from the font files, or forming them character
by character directly in run time.

MODULES ScrCur 

The cursor drawing module "ScrCur" supports the drawing of specific
graphics primitives with the following procedures applied:
creation, deletion, moving, hiding, vusualization, attribute
change, cursor type change. Any number of cursors may be on the
screen simultaneously. All the cursors are drawn in the xor mode.

Nowadays, the following cursors are implemented: marker, straight
line segment, hollow rectangle, character and string.

The most of parameters of cursor creation procedures are analogous
to the parameters of correspondent output primitives, except of two
differences. First difference is opaque type parameter, which is
always situated on the last place in the parameter list of the
cursor creation procedure. The pointer to the created cursor is
assigned to this parameter by this procedure, and is used for
cursor control by all the other procedures. Second difference is
the result, returned by the cursor creation procedure and used for
giving information about non-successful cursor creation due to
memory limitations.

Marker and rectangle cursors may be used in graphics input
procedures.

Character cursors may be used for creation arrows and icons. String
cursors are complex objects, which unlike another cursors, have
internal structure. For example, character string, representing the
cursor, may be edited and analyzed. String cursors are convenient
in text input procedures.

MODULES ScrInp 

Input module "ScrInp" supports the input of graphics and text data.
The procedures of point, rectangle and string input are implemented.

First, input procedures draw the object in its initial state, and
then begin the dialogue with the user, which can modify this state.
Current state of the object is shown on the screen by corresponding
cursor, i.e. by the object, which is able to move all over the
screen. One can use complex cursors, for example, the marker cross.
Complex object may be also modified, and additional cursors may be
used for this purpose. For example, in rectangle input its current
corner can be highlighted by the marker, or in string input its
current character can be highlighted by the special character
cursor.

Two colors are used in cursor drawing. The main color is used to
draw a main object, and the auxiliary color is used to draw an
additional cursor, i.e. corner marker or current character cursor.
The marker style and size are defined by corresponding attributes,
and the pattern for character cursor is defined by the fill
stipple number.

Dialogue with the user is done with the aid of the action-returning
procedure, which translates user's commands into some
hardware-independent "actions". These actions are interpreted by
the input procedure. The user can both use standard
action-returning procedures "ScrInp.GetPos" or "ScrInp.GetTxt",
being in the input module, or write and substitute her/his own
action-returning procedure.

Action-returning procedure has the parameter, which may be
considered as waiting procedure. This last procedure is to be
called in the poll cycle. The user is able to create interesting
effects by waiting procedure. For example, one can accompany input
actions with noise or, some time after, make the action-returning
procedure to receive actions from the disk file.

Hardware-independent actions, returned by action-returning
procedure, are defined by constants from enumeration type "Action".
The first three places in this type are occupyied by constants
"enter", "escape" and "move". These constants mean normal
input termination, break input and object moving accordingly.

In normal termination the input procedure returns current state of
input object. After break input the procedure returns the state,
being determined on the entry to the procedure, i.e. all the input
is ignored.

Output viewport, set on the pixel map, is taken into account during
input. For example, in string input, current position cursor can't
leave the viewport. So, if user moves to the right the cursor,
being on the right margin of the viewport, this follows to
automatic scrolling the string to the left. Analogous scrolling
will be done during moving the cursor to the left, if it is
situated on the left margin.


Chapter 4. WINDOW LEVEL


Window level contains the window management module, providing
general window operations. This module is the base for a group of
modules, containing window versions of graphics input and output
primitives.

MODULE Win 

Window manager "Win" performs the following operations upon
windows: opening and closing, hiding and showing, layering, moving
and resizing, framing and titling. The window manager supports the
automatic buffering of the drawing stream, i.e. each window has the
memory-based buffer (i.e. pixel map), which is used when the window
is hidden, partially invisible, or fully invisible.

The window is the virtual screen of any size, having the frame and
the title. The size and position of the window on the screen, as
well as relative positions of the windows, may vary during the
program execution. The windows may be hidden, i.e. invisible. If
the window isn't completely visible or hidden, it has the buffer,
and all window drawing operations don't draw on the screen, but act
on the buffer. There is the window update procedure, which copies
the window buffer onto the screen, and other window aren't
disturbed. Windows are able to be greater than the screen, to cross
the screen margin or to be completely out of the screen - for
example, on the invisible part of the screen page.

All the window manpulation procedures (except showing) may be
performed even when the display adapter is in the text mode. Window
showing becames possible only after turning display adapter to the
graphics mode.

A number of parameters, defining the window form on its creation,
are united in the record type "Win.Attrs". Its fields are called
window "attributes". Pointers of opaque type "Win.WINDOW" are used
to refer to windows.

All window procedures use all the memory resources very
intensively. If these resources are sufficient, all the procedures
return the result "Res.done", otherwise - the result
"Res.noMemory". We recommend to use extended memory models for
applications, where a lot of windows are involved.

MODULES WinOut, WinCur, WinIn 

Module "Win" is the base for three modules, containing the window
versions of graphics input and output primitives.

Window primitives calles are analogues to the corresponding ones of
the screen level. The single difference is - the place of the pixel
map parameter is occupied by the window parameter. This analogy
permits to transfer from the screen style to the window one and
back with minimum changes in the user's program.


Chapter 5. DIALOGUE LEVEL


Dialogue level is a group of modules providing the dialogue
interface construction.

MODULE Dlg 

Module "Dlg" permits to create the data structure, called "plex",
and use it to organize the dialogue with the program. Only part of
procedures of the module are to be called in user's program
- namely, procedures of creation and deletion of plexes. The rest
of procedures are used by the dialogue module "DlgInp".

The "plex" notion permits to define universally such components of
the dialogue, as message windows, menus, text data input panels,
help systems, running lines etc.

Plex is a set of special graphics windows, called "boxes",
intended to carry out a group of interconnected dialogue actions.
For example, the set of error messages, which can be generated by
one program block, may constitute one plex. Another example of plex
- the set of texts, used by the help system. Plex is defined by
its text description in special compact language.

The operations upon the boxes, constructing the plex, are analogues
to general window operations - i.e. hiding, showing and moving. In
setting the plex, all its boxes are also set. Some text strings,
existing in the box, are distinguished - they are called "items".
One of these items is the current one, and there is an opportunity
to set and get the current item by different means. In setting the
box, all its items are also set.

The items have the parameters: "name", "picture", "type" and "key".
The item name is the string, which is visible in showing the box,
containing the item. Picture is the string, consisting of
underbars, which may be replaced by data during the box showing.
The picture may be absent. Item type and key define the rules, by
which the client module may interprete the item. These parameters
are only set and get in the module, but not interpreted.

The source for creating the plex is its text description in
special language, and the attributes, defining colors and geometry
features. As a rule, the text description of all program plexes is
storaged apart from the program executive module, for example, in
text files. This differentiation permits to adapt the program
behaviour to the user's demands.

MODULE DlgInp 

Dialogue interfaces are constructed on the base of plexes, using
the wide opportunities of box control, provided by the module
"Dlg". Plexes, in connection with the set of interface procedures
of module "DlgInp", permit to create the hierarchy and network
menu systems with the features of text and graphics data input and
output, as well as help systems.

Pair of interface procedures to be written by the user, is used to
connect with user program context. The first of these procedures is
called in showing the box and initializes all the data pictures in
the box items. The second procedure is called when user presses the
key "Enter" (if the current item has the corresponding type) and
may be used in editing the data, user's procedures calls etc.

Module "DlgInp" contains two procedures. The procedure "DlgInp.Act"
activies the dialogue interface, i.e. on calling this procedure
the user gets control and can move through the active plex boxes,
pass from the box to the box and call the interface procedure,
manipulating the keys and mouse. The procedure "DlgInp.Show"
provides the passive data visualization, i.e. in calling this
procedure box items are scanned, and picture initialization
procedure is called on all items, having nonempty picture field.

In calling interface procedure, the module "Dlg" provides two
parameters. The first parameter is the box window, and the second
one is the key of current box item. This key may be used by the
interface procedure to select, for example, the needed user's
global variable, the value of which is to be shown in the picture
field of the current box item.

Analogues to all the input procedures the dialogue with the user
is performed with the aid of action-returning procedure, which
translates the user's commands to some hardware-independent
"actions". These actions are interpreted by the procedure
"DlgInp.Act". The user can both use the standard action-returning
procedure "DlgInp.Get" or write and use her/his own
action-returning procedure.

Hardware-independent actions, returned by action-returning
procedure, are defined by constants from enumeration type
"DlgInp.Action".


Chapter 6. LIBRARY SOURCES


The library is written so that it can be compiled by TopSpeed
Modula-2 compiler Ver 1.17 and Ver 3.10, and in almost any memory
model you like. The library contains all the necessary code
fragments to support DOS and TopSpeed DOS Extender operating
environments.

Extended memory models, supplied by TopSpeed DOS Extender, permit
to get over the 640-Kbytes barrier, existing in the MSDOS. The
program, being compiled and linked in this memory model, is able to
use the whole core memory for code and data storage. This is
achieved by the 80286/80386/80486/80586 processor, running the basic
part of the user program in the protected mode.

Library sources may be compiled by the Stony Brook Modula-2
compiler Ver 2.2 too. Before the compilation the sources must be
converted by the special convertor program, which is supplied with
the sources. It is necessary because TopSpeed and Stony Brook
compilers use different constructs for conditional compilation.

Given sources of the MultiGraph-2 library, user is able to use all
the functionality of these modern software development systems.
