doc/old/api.doc

GRX graphics library user's manual, version 2.0
===============================================


THIS FILE IS UNDER CONSTRUCTION!!!!!!!
Use the 1.03 user's manual for description of the library functions and
consult "grx20.h"

The most important differences:
1) COLORS ARE LONG!!!!
2) NO WIDE LINES AND PATTERNED FILLS YET!
3) NO GrFindBestFont(), NO INTEGER FONT MAGNIFICATION,
   BUT FONTS CAN BE SCALED
4) ARCS HAVE AN EXTRA PARAMETER, WHICH IS THE STYLE FOR CLOSING THEM


==================== Don't read after this =============================


Abstract

LIBGRX is a graphics library for DJGPP or Turbo C programs. (The Turbo
C version was tested using TC++ 1.01) Currently it supports VGA (32768,
256 or 16 colors), EGA (16 colors), 8514/A (256 colors) and S3-based (256
colors) cards. Planned future improvements include support for Hercules
cards as well. It is upward compatible with the graphics library in DJGPP
(the C part, no C++ classes). It can use the same drivers as the graphics
library in DJGPP or it can work with a new driver format supporting
programmable number of colors as well.


Data types, function declarations

All public data structures and graphics primitives meant for usage by
the application program are declared/prototyped in the header files (in the
'include' sub-directory):

GRDRIVER.H graphics driver format specifications
MOUSEX.H cursor, mouse and keyboard handling
GRX.H drawing-related structures and functions
GRXFILE.H file formats and file access routines
GRXFONT.H format of a font when loaded into memory


Setting video modes

Before a program can do any graphics drawing it has to configure the
display adapter of the PC for the desired graphics mode. It is done with the
'GrSetMode' function as follows:

#ifdef __cplusplus
void GrSetMode(int which,int width=0,int height=0,int colors=0);
#else
void GrSetMode(int which,...);
#endif

The 'mode' parameter can be one of the following constants, declared in
"grx.h":

typedef enum {
GR_80_25_text,
GR_default_text,
GR_width_height_text,
GR_biggest_text,
GR_320_200_graphics,
GR_default_graphics,
GR_width_height_graphics,
GR_biggest_noninterlaced_graphics,
GR_biggest_graphics,
GR_width_height_color_graphics


LIBGRX graphics library user's manual 3


} GR_graphics_modes;

The 'GR_width_height_text' and 'GR_width_height_graphics' modes require
the two optional size arguments, and the 'GR_width_height_color_graphics' mode
requires all three optional arguments. A call with any other mode does not
require any of the optional arguments.

NOTE: the 'GR_width_height_color_graphics' mode is a new mode supported only
if: (1) you have a new format graphics driver (see the accompanying
documentation in the file "DRIVERS.DOC"), and (2) you have a recent (version
1.06, dated after the middle of April 1992) copy of GO32 which knows how to
deal with the new driver format.

New format graphics drivers operating in the proper environment (see above)
can provide a table of the supported text and graphics modes using:

void GrGetDriverModes(GR_DRIVER_MODE_ENTRY **ttable,GR_DRIVER_MODE_ENTRY **gtable)

The arguments 'ttable' and 'gtable' should be addresses of pointers to the
'GR_DRIVER_MODE_ENTRY' structure defined in the include file "grdriver.h".
Upon return the pointer variables will point to two arrays of these
structures, one for the text modes, the other for graphics. The
'GR_DRIVER_MODE_ENTRY' structure has the following fields:

typedef struct {
unsigned short width;
unsigned short height;
unsigned short number_of_colors;
unsigned char BIOS_mode;
unsigned char special;
} GR_DRIVER_MODE_ENTRY;

The first four structure members should be obvious, but the 'special'
field may deserve some explanation. It is non-zero if the driver does some
special "tricks" to put the card into the desired mode. An example might be
the 43 row EGA text mode: for this first the "standard" 80x25 text mode is
set up and then the character generator is re-loaded with a smaller font.
If the 'special' field is zero then the driver simply invokes the INT 10
function 0 BIOS routine with the mode in the 'BIOS_mode' slot.

A user-defined function can be invoked every time the video mode is
changed (i.e. 'GrSetMode' is called). This function should not take any
parameters and its return value (if any) is ignored. It can be installed
(for all subsequent 'GrSetMode' calls) with the:

void GrSetModeHook(void (*callback)(void));

function. The current graphics mode (one of the valid 'mode' argument values
for 'GrSetMode') can be obtained with the:

int GrCurrentMode(void);


LIBGRX graphics library user's manual 4


function, while the type of the installed graphics adapter can be determined
with the

int GrAdapterType(void);

function. 'GrAdapterType' returns the type of the adapter as one of the
following three symbolic constants (defined in "grx.h"):

#define GR_VGA 0 /* VGA adapter */
#define GR_EGA 1 /* EGA adapter */
#define GR_HERC 2 /* Hercules mono adapter */
#define GR_8514A 3 /* 8514/A or compatible */
#define GR_S3 4 /* S3 graphics accelerator */


LIBGRX graphics library user's manual 5


Graphics contexts

The library supports a set of drawing regions called 'contexts' (the
'GrContext' structure). These can be in video memory or in system memory.
Contexts in system memory always have the same memory organization as the
video memory. When 'GrSetMode' is called, a default context is created which
maps to the whole graphics screen. Contexts are described by the 'GrContext'
data structure:

typedef struct _GR_context_ {
char far *gc_baseaddr; /* base address of display memory */
long gc_frameaddr; /* upper left corner coordinate */
long gc_planeoffset; /* offset to next color plane */
int gc_lineoffset; /* offset to next scan line in bytes */
char gc_onscreen; /* is it in video memory ? */
char gc_memflags; /* memory allocation flags */
int gc_xmax; /* max X coord (width - 1) */
int gc_ymax; /* max Y coord (height - 1) */
int gc_xcliplo; /* low X clipping limit */
int gc_ycliplo; /* low Y clipping limit */
int gc_xcliphi; /* high X clipping limit */
int gc_ycliphi; /* high Y clipping limit */
int gc_usrxbase; /* user window min X coordinate */
int gc_usrybase; /* user window min Y coordinate */
int gc_usrwidth; /* user window width */
int gc_usrheight; /* user window height */
int gc_xoffset; /* X offset from root's base */
int gc_yoffset; /* Y offset from root's base */
struct _GR_context_ *gc_root; /* context which owns frame buf */
} GrContext;

There is a subtype of the 'GrContext' structure. The structure
'GrVidRAM' contains only the first slots of a context describing the memory
layout of a context. This structure is used as a component of other more
complex data structures in the library.

typedef struct {
char far *gc_baseaddr; /* base address of display memory */
long gc_frameaddr; /* upper left corner coordinate */
long gc_planeoffset; /* offset to next color plane */
int gc_lineoffset; /* offset to next scan line in bytes */
char gc_onscreen; /* is it in video memory ? */
char gc_memflags; /* memory allocation flags */
} GrVidRAM;

The following four functions return information about the layout of and
memory occupied by a graphics context of size 'width' by 'height' in the
current graphics mode (as set up by 'GrSetMode'):

int GrLineOffset(int width);
int GrNumPlanes(void);


LIBGRX graphics library user's manual 6


long GrPlaneSize(int w,int h);
long GrContextSize(int w,int h);

'GrLineOffset' always returns the offset between successive pixel rows of the
context in bytes. 'GrNumPlanes' returns the number of bitmap planes in the
current graphics mode. 'GrContextSize' calculates the total amount of memory
needed by a context, while 'GrPlaneSize' calculates the size of a bitplane in
the context. The function:

GrContext *GrCreateContext(int w,int h,char far *memory,GrContext *where);

can be used to create a new context in system memory. The NULL pointer is also
accepted as the value of the 'memory' and 'where' arguments, in this case the
library allocates the necessary amount of memory internally.

It is a general convention in the library that functions returning
pointers to any LIBGRX specific data structure have a last argument (most of
the time named 'where' in the prototypes) which can be used to pass the
address of the data structure which should be filled with the result. If this
'where' pointer has the value of NULL, then the library allocates space for
the data structure internally.

The function:

GrContext *GrCreateSubContext(int x1,int y1,int x2,int y2,GrContext *parent,GrContext *where);

creates a new sub-context which maps to a part of an existing context. The
coordinate arguments ('x1' through 'y2') are interpreted relative to the
parent context's limits. Pixel addressing is zero-based even in sub-contexts,
i.e. the address of the top left pixel is (0,0) even in a sub-context which
has been mapped onto the interior of its parent context.

Sub-contexts can be resized, but not their parents (i.e. anything
returned by 'GrCreateContext' or set up by 'GrSetMode' cannot be resized --
because this could lead to irrecoverable "loss" of drawing memory. The
following function can be used for this purpose:

void GrResizeSubContext(GrContext *context,int x1,int y1,int x2,int y2);

The current context structure is stored in a static location in the
library. (For efficiency reasons -- it is used quite frequently, and this way
no pointer dereferencing is necessary.) The context stores all relevant
information about the video organization, coordinate limits, etc... The
current context can be set with the:

void GrSetContext(GrContext *context);

function. This function will reset the current context to the full graphics
screen if it is passed the NULL pointer as argument. The value of the current
context can be saved into a 'GrContext' structure pointed to by 'where' using:


LIBGRX graphics library user's manual 7


GrContext *GrSaveContext(GrContext *where);

(Again, if 'where' is NULL, the library allocates the space.) Contexts can be
destroyed with:

void GrDestroyContext(GrContext *context);

This function will free the memory occupied by the context only if it was
allocated originally by the library. The next three functions set up and query
the clipping limits associated with the context:

void GrSetClipBox(int x1,int y1,int x2,int y2);
void GrGetClipBox(int *x1p,int *y1p,int *x2p,int *y2p);
void GrResetClipBox(void);

'GrResetClipBox' sets the clipping limits to the limits of context. These are
the limits set up initially when a context is created. The limits of the
current context can be obtained using the following functions:

int GrMaxX(void);
int GrMaxY(void);
int GrSizeX(void);
int GrSizeY(void);

The 'Max' functions return the biggest valid coordinate, while the 'Size'
functions return a value one higher. The limits of the graphics screen
(regardless of the current context) can be obtained with:

int GrScreenX(void);
int GrScreenY(void);


Color management

The library supports two models for color management. In the 'indirect'
(or color table) mode colors can be allocated with the highest resolution
supported by the hardware (EGA: 2 bits, VGA: 6 bits) with respect to the
component color intensities. In the 'direct' or RGB mode color indices map
directly into component color intensities with non-overlapping bitfields of
the color index representing the component colors. The RGB mode is supported
in 256 color and 32768 color VGA modes only (for 32768 colors this is the only
mode because of the limitations of the VGA hardware with HiColor DAC). In RGB
mode the color index maps to component color intensities as follows:

256: rrrgggbb (3 bits for red and green, 2 for blue)
32768: xrrrrrgggggbbbbb (5 bits for each component color)

The RGB mode is not supported in 16 color EGA and VGA modes as there are
too few available colors to provide adequate coverage. The advantage of the
RGB mode is faster color allocation (no table lookup, DAC register


LIBGRX graphics library user's manual 8


programming, etc...) its disadvantage is the relatively crude approximation of
the component color intensities.

After the first 'GrSetMode' call two colors are always defined: black
and white. The indices of these two colors are returned by the functions:

int GrBlack(void);
int GrWhite(void);

NOTE: unlike the original DJGPP library, LIBGRX does not guarantee that the
white color
has the color index value of one. (GrBlack still returns 0).

The library supports four write modes: write, XOR, logical OR and
logical AND. These can be selected with OR-ing the color index with one of the
following constants declared in "grx.h":

#ifdef __TURBOC__
# define GrXOR 0x100 /* to "XOR" any color to the screen */
# define GrOR 0x200 /* to "OR" to the screen */
# define GrAND 0x300 /* to "AND" to the screen */
#endif
#ifdef __GNUC__ /* changed for 16 bit colors */
# define GrXOR 0x10000 /* to "XOR" any color to the screen */
# define GrOR 0x20000 /* to "OR" to the screen */
# define GrAND 0x30000 /* to "AND" to the screen */
#endif
#define GrWRITE 0 /* write color */
#define GrNOCOLOR (GrXOR | 0) /* GrNOCOLOR is used for "no" color */

NOTE: 'GrXOR' was declared to be "0x100" in the original DJGPP library, but
its value had to be changed in LIBGRX in anticipation of the 32768 color VGA
support.

By convention, the no-op color is obtained by combining color index 0 (black)
with the XOR operation. This no-op color has been defined in "grx.h" as
'GrNOCOLOR'.

The number of colors in the current graphics mode is returned by the:

int GrNumColors(void);

function, while the number of unused, available color can be obtained by
calling:

int GrNumFreeColors(void);

Colors can be allocated with the:

int GrAllocColor(int r,int g,int b);


LIBGRX graphics library user's manual 9


function (component intensities can range from 0 to 255), or with the:

int GrAllocCell(void);

function. In the second case the component intensities of the returned color
can be set with:

void GrSetColor(int color,int r,int g,int b);

Both 'Alloc' functions return 'GrNOCOLOR' if there are no more free colors
available. Additionally 'GrAllocCell' always returns 'GrNOCOLOR' when the
color system is in RGB mode, as colors returned by 'GrAllocCell' are meant to
be changed -- what is not supposed to be done in RGB mode. Also note that
'GrAllocColor' operates much more efficiently in RGB mode, and that it never
returns 'GrNOCOLOR' in this case.

Color table entries can be freed (when not in RGB mode) by calling:

void GrFreeColor(int color);

The component intensities of any color can be queried using the function:

void GrQueryColor(int c,int *r,int *g,int *b);

Initially the color system is in color table (indirect) mode. (Except
for the 32768 color VGA modes which are always in RGB mode.) 256 color VGA
modes can be put into the RGB mode by calling:

void GrSetRGBcolorMode(void);

The color system can be reset (i.e. put back into color table mode if
possible, all colors freed except for black and white) by calling:

void GrResetColors(void);

The function:

void GrRefreshColors(void);

reloads the currently allocated color values into the video hardware. This
function is not needed in typical applications, unless the display adapter is
programmed directly by the application.

Graphics primitives

The screen, the current context or the current clip box can be cleared
(i.e.set toadesired backgroundcolor)by usingoneof thefollowingthree functions:

void GrClearScreen(int bg);
void GrClearContext(int bg);
void GrClearClipBox(int bg);


LIBGRX graphics library user's manual 10


The following line drawing graphics primitives are supported by the library:

void GrPlot(int x,int y,int c);
void GrLine(int x1,int y1,int x2,int y2,int c);
void GrHLine(int x1,int x2,int y,int c);
void GrVLine(int x,int y1,int y2,int c);
void GrBox(int x1,int y1,int x2,int y2,int c);
void GrCircle(int xc,int yc,int r,int c);
void GrEllipse(int xc,int yc,int xa,int ya,int c);
void GrCircleArc(int xc,int yc,int r,int start,int end,int c);
void GrEllipseArc(int xc,int yc,int xa,int ya,int start,int end,int c);
void GrPolyLine(int numpts,int points[][2],int c);
void GrPolygon(int numpts,int points[][2],int c);

All primitives operate on the current graphics context. The last argument of
these functions is always the color index to use for the drawing. The
'HLine' and 'VLine' primitives are for drawing horizontal and vertical
lines. They have been included in the library because they are more
efficient than the general line drawing provided by 'GrLine'. The ellipse
primitives can only draw ellipses with their major axis parallel with either
the X or Y coordinate axis. They take the half X and Y axis length in the
'xa' and 'ya' arguments. The arc (circle and ellipse) drawing functions take
the start and end angles in tenths of degrees (i.e. meaningful range: 0 ...
3600). The angles are interpreted counter-clockwise starting from the
positive X axis. The polyline and polygon primitives take the address of an
n by 2 coordinate array. The X values should be stored in the elements with
0 second index, and the Y values in the elements with a second index value
of 1. Coordinate arrays passed to the polygon primitives can either contain
or omit the closing edge of the polygon -- the primitive will append it to
the list if it is missing.

The following filled primitives are available:

void GrFilledBox(int x1,int y1,int x2,int y2,int c);
void GrFramedBox(int x1,int y1,int x2,int y2,int wdt,const GrFBoxColors *c);
void GrFilledCircle(int xc,int yc,int r,int c);
void GrFilledEllipse(int xc,int yc,int xa,int ya,int c);
void GrFilledCircleArc(int xc,int yc,int r,int start,int end,int c);
void GrFilledEllipseArc(int xc,int yc,int xa,int ya,int start,int end,int c);
void GrFilledPolygon(int numpts,int points[][2],int c);
void GrFilledConvexPolygon(int numpts,int points[][2],int c);

Similarly to the line drawing, all of the above primitives operate on
the current graphics context. The 'GrFramedBox' primitive can be used to draw
motif-like shaded boxes and "ordinary" framed boxes as well. The 'x1' through
'y2' coordinates specify the interior of the box, the border is outside this
area. The primitive uses five different colors for the interior and four
borders of the box which are specified in the 'GrFBoxColors' structure:

typedef struct {
int fbx_intcolor;
int fbx_topcolor;


LIBGRX graphics library user's manual 11


int fbx_rightcolor;
int fbx_bottomcolor;
int fbx_leftcolor;
} GrFBoxColors;

The 'GrFilledConvexPolygon' primitive can be used to fill convex polygons. It
can also be used to fill some concave polygons whose boundaries do not
intersect any horizontal scan line more than twice. All other concave polygons
have to be filled with the (somewhat less efficient) 'GrFilledPolygon'
primitive. This primitive can also be used to fill several disjoint non-
overlapping polygons in a single operation.

The current color value of any pixel in the current context can be obtained
with:

int GrPixel(int x,int y);

Rectangular areas can be transferred within a context or between contexts by
calling:

void GrBitBlt(GrContext *dest,int x,int y,GrContext *source,int x1,int y1,int x2,int y2,int oper);

The 'oper' argument should be one of supported color modes (write, XOR, OR,
AND), it will control how the pixels from the source context are combined with
the pixels in the destination context. If either the source or the destination
context argument is the NULL pointer then the current context is used for that
argument.


Non-clipping graphics primitives

There is a non-clipping version of some of the elementary primitives.
These are somewhat more efficient than the regular versions. These are to be
used only in situations when it is absolutely certain that no drawing will be
performed beyond the boundaries of the current context. Otherwise the program
will almost certainly crash! The reason for including these functions is that
they are somewhat more efficient than the regular, clipping versions. ALSO
NOTE: These function do not check for conflicts with the mouse cursor. (See
the explanation about the mouse cursor handling later in this document.) The
list of the supported non-clipping primitives:

void GrPlotNC(int x,int y,int c);
void GrLineNC(int x1,int y1,int x2,int y2,int c);
void GrHLineNC(int x1,int x2,int y,int c);
void GrVLineNC(int x,int y1,int y2,int c);
void GrBoxNC(int x1,int y1,int x2,int y2,int c);
void GrFilledBoxNC(int x1,int y1,int x2,int y2,int c);
void GrFramedBoxNC(int x1,int y1,int x2,int y2,int wdt,const GrFBoxColors *c);
void GrBitBltNC(GrContext *dst,int x,int y,GrContext *src,int x1,int y1,int x2,int y2,int oper);
int GrPixelNC(int x,int y);


LIBGRX graphics library user's manual 12


Customized line drawing

The basic line drawing graphics primitives described previously always
draw continuous lines which are one pixel wide. There is another group of line
drawing functions which can be used to draw wide and/or patterned lines. These
functions have similar parameter passing conventions as the basic ones with
one difference: instead of the color value a pointer to a structure of type
'GrLineOption' has to be passed to them. The definition of the 'GrLineOption'
structure:

typedef struct {
int lno_color; /* color used to draw line */
int lno_width; /* width of the line */
int lno_pattlen; /* length of the dash pattern */
unsigned char *lno_dashpat; /* draw/nodraw pattern */
} GrLineOption;

The 'lno_pattlen' structure element should be equal to the number of
alternating draw -- no draw section length values in the array pointed to by
the 'lno_dashpat' element. The dash pattern array is assumed to begin with a
drawn section. If the pattern length is equal to zero a continuous line is
drawn. The available custom line drawing primitives:

void GrCustomLine(int x1,int y1,int x2,int y2,const GrLineOption *o);
void GrCustomBox(int x1,int y1,int x2,int y2,const GrLineOption *o);
void GrCustomCircle(int xc,int yc,int r,const GrLineOption *o);
void GrCustomEllipse(int xc,int yc,int xa,int ya,const GrLineOption *o);
void GrCustomCircleArc(int xc,int yc,int r,int start,int end,const GrLineOption *o);
void GrCustomEllipseArc(int xc,int yc,int xa,int ya,int start,int end,const GrLineOption *o);
void GrCustomPolyLine(int numpts,int points[][2],const GrLineOption *o);
void GrCustomPolygon(int numpts,int points[][2],const GrLineOption *o);


Pattern filled graphics primitives

The library also supports a pattern filled version of the basic filled
primitives described above. These functions have similar parameter passing
conventions as the basic ones with one difference: instead of the color value
a pointer to an union of type 'GrPattern' has to be passed to them. The
'GrPattern' union can contain either a bitmap or a pixmap fill pattern. The
first integer slot in the union determines which type it is. Bitmap fill
patterns are rectangular arrays of bits, each set bit representing the
foreground color of the fill operation, and each zero bit representing the
background. Both the foreground and background colors can be combined with any
of the supported logical operations. Bitmap fill patterns have one
restriction: their width must be eight pixels. Pixmap fill patterns are very
similar to contexts, the data is transferred to the filled primitive using
'BitBlt' operations. The relevant structure declarations (from "grx.h"):

/*
* BITMAP: a mode independent way to specify a fill pattern of two


LIBGRX graphics library user's manual 13


* colors. It is always 8 pixels wide (1 byte per scan line), its
* height is user-defined. SET THE TYPE FLAG TO ZERO!!!
*/
typedef struct {
int bmp_ispixmap; /* type flag for pattern union */
int bmp_height; /* bitmap height */
unsigned char *bmp_data; /* pointer to the bit pattern */
int bmp_fgcolor; /* foreground color for fill */
int bmp_bgcolor; /* background color for fill */
int bmp_memflags; /* set if dynamically allocated */
} GrBitmap;

/*
* PIXMAP: a fill pattern stored in a layout identical to the video RAM
* for filling using 'bitblt'-s. It is mode dependent, typically one
* of the library functions is used to build it. KEEP THE TYPE FLAG
* NONZERO!!!
*/
typedef struct {
int pxp_ispixmap; /* type flag for pattern union */
int pxp_width; /* pixmap width (in pixels) */
int pxp_height; /* pixmap height (in pixels) */
int pxp_oper; /* bitblt mode (SET, OR, XOR, AND) */
GrVidRAM pxp_source; /* source context for fill */
} GrPixmap;

/*
* Fill pattern union -- can either be a bitmap or a pixmap
*/
typedef union {
int gp_ispixmap; /* nonzero for pixmaps */
GrBitmap gp_bitmap; /* fill bitmap */
GrPixmap gp_pixmap; /* fill pixmap */
} GrPattern;

#define gp_bmp_data gp_bitmap.bmp_data
#define gp_bmp_height gp_bitmap.bmp_height
#define gp_bmp_fgcolor gp_bitmap.bmp_fgcolor
#define gp_bmp_bgcolor gp_bitmap.bmp_bgcolor

#define gp_pxp_width gp_pixmap.pxp_width
#define gp_pxp_height gp_pixmap.pxp_height
#define gp_pxp_oper gp_pixmap.pxp_oper
#define gp_pxp_source gp_pixmap.pxp_source

Bitmap patterns can be easily built from initialized character arrays and
static structures by the C compiler, thus no special support is included in
the library for creating them. The only action required from the application
program might be changing the foreground and background colors as needed.
Pixmap patterns are more difficult to build as they replicate the layout of
the video memory which changes for different video modes. For this reason the


LIBGRX graphics library user's manual 14


library provides three functions to create pixmap patterns in a mode-
independent way:

GrPattern *GrBuildPixmap(const char *pixels,int w,int h,const GrColorTableP colors);
GrPattern *GrBuildPixmapFromBits(const char *bits,int w,int h,int fgc,int bgc);
GrPattern *GrConvertToPixmap(GrContext *src);

'GrBuildPixmap' build a pixmap from a two dimensional ('w' by 'h') array of
characters. The elements in this array are used as indices into the color
table specified with the argument 'colors'. (This means that pixmaps created
this way can use at most 256 colors.) The color table pointer:

typedef int *GrColorTableP;

should point to an array of integers with the first element being the number
of colors in the table and the color indices themselves starting with the
second element. NOTE: any color modifiers (GrXOR, GrOR, GrAND) OR-ed to the
elements of the color table are ignored.

The 'GrBuildPixmapFromBits' function builds a pixmap fill pattern from bitmap
data. It is useful if the width of the bitmap pattern is not eight as such
bitmap patterns can not be used to build a 'GrBitmap' structure.

The 'GrConvertToPixmap' function converts a graphics context to a pixmap fill
pattern. It is useful when the pattern can be created with graphics drawing
operations. NOTE: the pixmap pattern and the original context share the
drawing RAM, thus if the context is redrawn the fill pattern changes as well.

Fill patterns which were built by library routines can be destroyed when
no longer needed (i.e. the space occupied by them can be freed) by calling:

void GrDestroyPattern(GrPattern *p);

NOTE: when pixmap fill patterns converted from contexts are destroyed, the
drawing RAM is not freed. It is freed when the original context is destroyed.
Fill patterns built by the application have to be destroyed by the application
as well (if this is needed).

The list of supported pattern filled graphics primitives is shown below.
These functions are very similar to their solid filled counterparts, only
their last argument is different:

void GrPatternFilledPlot(int x,int y,GrPattern *p);
void GrPatternFilledLine(int x1,int y1,int x2,int y2,GrPattern *p);
void GrPatternFilledBox(int x1,int y1,int x2,int y2,GrPattern *p);
void GrPatternFilledCircle(int xc,int yc,int r,GrPattern *p);
void GrPatternFilledEllipse(int xc,int yc,int xa,int ya,GrPattern *p);
void GrPatternFilledCircleArc(int xc,int yc,int r,int start,int end,GrPattern *p);
void GrPatternFilledEllipseArc(int xc,int yc,int xa,int ya,int start,int end,GrPattern *p);
void GrPatternFilledConvexPolygon(int numpts,int points[][2],GrPattern *p);
void GrPatternFilledPolygon(int numpts,int points[][2],GrPattern *p);


LIBGRX graphics library user's manual 15


Strictly speaking the plot and line functions in the above group are not
filled, but they have been included here for convenience.


Patterned line drawing

The custom line drawing functions introduced above also have a version
when the drawn sections can be filled with a (pixmap or bitmap) fill pattern.
To achieve this these functions must be passed both a custom line drawing
option ('GrLineOption' structure) and a fill pattern ('GrPattern' union).
These two have been combined into the 'GrLinePattern' structure:

typedef struct {
GrPattern *lnp_pattern; /* fill pattern */
GrLineOption *lnp_option; /* width + dash pattern */
} GrLinePattern;

All patterned line drawing functions take a pointer to this structure as their
last argument. The list of available functions:

void GrPatternedLine(int x1,int y1,int x2,int y2,GrLinePattern *lp);
void GrPatternedBox(int x1,int y1,int x2,int y2,GrLinePattern *lp);
void GrPatternedCircle(int xc,int yc,int r,GrLinePattern *lp);
void GrPatternedEllipse(int xc,int yc,int xa,int ya,GrLinePattern *lp);
void GrPatternedCircleArc(int xc,int yc,int r,int start,int end,GrLinePattern *lp);
void GrPatternedEllipseArc(int xc,int yc,int xa,int ya,int start,int end,GrLinePattern *lp);
void GrPatternedPolyLine(int numpts,int points[][2],GrLinePattern *lp);
void GrPatternedPolygon(int numpts,int points[][2],GrLinePattern *lp);


Text drawing

The library supports loadable bit-mapped (i.e. not scalable!) fonts.
Some of these fonts were converted from VGA BIOS fonts and fonts on utility
diskettes coming with VGA cards. These fonts have all 256 characters. Some
additional fonts were converted from fonts in the MIT X11 distribution. These
have a variable number of characters, some support all 256 character codes,
some only the printable ASCII codes. Fonts also have family names, which are
used in a font lookup procedure supported by the library (see later). The
following font families are included in the distribution:


LIBGRX graphics library user's manual 16


Font file name: Family: Description:

pc<W>x<H>[t].fnt pc BIOS font, fixed
xm<W>x<H>[b][i].fnt X_misc X11, fixed, miscellaneous group
char<H>[b][i].fnt char X11, proportional, charter family
cour<H>[b][i].fnt cour X11, fixed, courier
helve<H>[b][i].fnt helve X11, proportional, helvetica
lucb<H>[b][i].fnt lucb X11, proportional, lucida bright
lucs<H>[b][i].fnt lucs X11, proportional, lucida sans serif
luct<H>[b][i].fnt luct X11, fixed, lucida typewriter
ncen<H>[b][i].fnt ncen X11, proportional, new century schoolbook
symb<H>.fnt symbol X11, proportional, greek letters,
symbols
tms<H>[b][i].fnt times X11, proportional, times

In the font names <W> means the font width, <H> the font height. Many font
families have bold and/or italic variants. The files containing these fonts
contain a 'b' and/or 'i' character in their name just before the extension.
Additionally, the strings "_bold" and/or "_ital" are appended to the font
family names. Some of the pc BIOS fonts come in thin formats also, these are
denoted by a 't' in their file names and the string "_thin" in their family
names.

NOTE: the basic libgrx distribution ("cbgrx101.zip") contains only the full
"pc", "courier", "helve", "symbol" and "times" font families and selected
sizes from the "X_misc" family. (Because of archive size considerations!) The
full compliment of fonts can be found in the archive file named
"cbgrxfnt.zip", which should be available from the same site where the basic
library was obtained from.

Fonts are loaded with the 'GrLoadFont' function. If the font file name
starts with any path separator character or character sequence ('<drive
letter>:', '/' or '\') then it is loaded from the specified directory,
otherwise the font is loaded from the default font path. The font path can be
set up with the 'GrSetFontPath' function. If the font path is not set then the
value of the 'GRXFONT' environment variable is used as the font path. If
'GrLoadFont' is called again with the name of an already loaded font then it
will return a pointer to the result of the first loading. The special font
names "@:pc8x8.fnt", "@:pc8x14.fnt" and "@:pc8x16.fnt" will cause 'GrLoadFont'
to load the font from the BIOS of the graphics card of the PC (provided that
it has the desired font). Alternatively, 'GrLoadBIOSFont' can also be called
to load a font which resides in the BIOS of the display adapter. (The
difference is that 'GrLoadFont' will look at the disk as well if the BIOS does
not have the font. For example: EGA-s don't have a 16 row font in their BIOS.)
Both font loading routines return NULL if the font was not found. When not
needed any more, fonts can be unloaded (i.e. the storage occupied by them
freed) by calling 'GrUnloadFont'. The prototype declarations for these
functions:

GrFont *GrLoadFont(char *name);
GrFont *GrLoadBIOSFont(char *name);


LIBGRX graphics library user's manual 17


void GrUnloadFont(GrFont *font);
void GrSetFontPath(char *path);

The 'GrFont' structure is actually a font header, the real font data is
right next to this header in memory, but it is typically hidden from the
application program. If needed, the include file "grxfont.h" can provide more
details. The 'GrFont' structure:

typedef struct {
short fnt_width; /* width (average for proportional) */
short fnt_height; /* font height */
short fnt_minchar; /* lowest character code in font */
short fnt_maxchar; /* highest character code in font */
short fnt_isfixed; /* nonzero if fixed font */
short fnt_internal; /* nonzero if BIOS font */
short fnt_baseline; /* baseline from top of font */
short fnt_undwidth; /* underline width (at bottom) */
char fnt_name[GR_NAMEWIDTH]; /* font file name (w/o path) */
char fnt_family[GR_NAMEWIDTH]; /* font family name */
} GrFont;

There is a function: 'GrFindBestFont' which returns the font which
matches best a desired size. (Best match: not bigger, but as close as
possible). The application can specify whether it wants 'GrFindBestFont' to
find the best match using fonts in their original sizes only, or possibly
enlarged (with the value of the 'magnify' argument -- 0: no, nonzero: yes).
'GrFindBestFont' also takes a string argument which specifies the font family
from which to select the font. The string can specify several family patterns
separated by the ':' character. Each pattern can contain the '?' and '*'
wildcard characters which work the usual way (in UNIX sense -- i.e. "X*ital"
will match "X_misc_ital", but not "X_misc_bold"..).

GrTextOption *GrFindBestFont(int width,int height,int magnify,char *family,GrTextOption *where);

The 'GrTextOption' structure specifies how to draw a character string:

typedef struct {
GrFont *txo_font; /* font to be used */
int txo_xmag; /* X magnification */
int txo_ymag; /* Y magnification */
union {
int v; /* color when no attributes */
GrColorTableP p; /* ptr to color table otherwise */
} txo_fgcolor,txo_bgcolor; /* foreground, background */
char txo_direct; /* direction */
char txo_xalign; /* X alignment */
char txo_yalign; /* Y alignment */
char txo_chrtype; /* character type */
} GrTextOption;


LIBGRX graphics library user's manual 18


The font can be enlarged independently in the X and Y directions, ('txo_xmag'
and 'txo_ymag' slots -- values: 1 and up) the text can be rotated in
increments of 90 degrees ('txo_direct'), alignments can be set in both
directions ('txo_xalign' and 'txo_yalign'), and separate fore and background
colors can be specified. The accepted text direction values:

#define GR_TEXT_RIGHT 0 /* normal */
#define GR_TEXT_DOWN 1 /* downward */
#define GR_TEXT_LEFT 2 /* upside down, right to left */
#define GR_TEXT_UP 3 /* upward */
#define GR_TEXT_DEFAULT GR_TEXT_RIGHT

The accepted horizontal and vertical alignment option values:

#define GR_ALIGN_LEFT 0 /* X only */
#define GR_ALIGN_TOP 0 /* Y only */
#define GR_ALIGN_CENTER 1 /* X, Y */
#define GR_ALIGN_RIGHT 2 /* X only */
#define GR_ALIGN_BOTTOM 2 /* Y only */
#define GR_ALIGN_BASELINE 3 /* Y only */
#define GR_ALIGN_DEFAULT GR_ALIGN_LEFT

Text strings can be of three different types: one character per byte (i.e. the
usual C character string, this is the default), one character per 16-bit word
(suitable for fonts with a large number of characters), and a PC-style
character-attribute pair. In the last case the 'GrTextOption' structure must
contain a pointer to a color table of size 16 (fg color bits in attrib) or 8
(bg color bits). (The color table format is explained in more detail in the
previous section explaining the methods to build fill patterns.) The supported
text types:

#define GR_BYTE_TEXT 0 /* one byte per character */
#define GR_WORD_TEXT 1 /* two bytes per character */
#define GR_ATTR_TEXT 2 /* char w/ PC style attribute byte */

The PC-style attribute text uses the same layout (first byte: character,
second: attributes) and bitfields as the text mode screen on the PC. The only
difference is that the 'blink' bit is not supported (it would be very time
consuming -- the PC text mode does it with hardware support). This bit is used
instead to control the underlined display of characters. For convenience the
following attribute manipulation macros have been declared in "grx.h":

#define GR_BUILD_ATTR(fgcolor,bgcolor,underline) \
((fgcolor) & 15) | (((bgcolor) & 7) << 4) | (((underline) & 1) << 7))
#define GR_ATTR_FGCOLOR(attr) ((attr) & 15)
#define GR_ATTR_BGCOLOR(attr) (((attr) >> 4) & 7)
#define GR_ATTR_UNDERLINE(attr) (((attr) >> 7) & 1)

Text strings of the types 'GR_BYTE_TEXT' and 'GR_WORD_TEXT" can also be drawn
underlined. This is controlled by OR-ing the constant 'GR_UNDERLINE_TEXT' to
the foreground color value:


LIBGRX graphics library user's manual 19


#define GR_UNDERLINE_TEXT (GrXOR << 6)

After the application initializes a text option structure with the
desired values it can call one of the following two text drawing functions:

void GrDrawChar(int chr,int x,int y,const GrTextOption *opt);
void GrDrawString(char *text,int length,int x,int y,const GrTextOption *opt);

NOTE: text drawing is fastest when the font is not magnified, it is drawn in
the 'normal' direction, and the character does not have to be clipped. It this
case the library can use the appropriate low-level video RAM access routine
(see "INTERNAL.DOC" for more details), while in any other case the text is
drawn pixel-by-pixel (or rectangle-by-rectangle if enlarged) by the
higher-level code.

The function 'GrTextXY' is provided for compatibility with the original
256 color DJGPP graphics library. It draws the text in the standard direction,
unmagnified, and using the 16 row BIOS font on VGA-s or the 14 row font on
EGA-s.

void GrTextXY(int x,int y,char *text,int fg,int bg);

The size of a font, a character or a text string can be obtained by
calling one of the following functions. These functions also take into
consideration the magnification and text direction specified in the text
option structure passed to them.

int GrFontHeight(GrTextOption *opt);
int GrFontWidth(GrTextOption *opt);
int GrCharWidth(int chr,const GrTextOption *opt);
int GrCharHeight(int chr,const GrTextOption *opt);
int GrStringWidth(char *text,int length,const GrTextOption *opt);
int GrStringHeight(char *text,int length,const GrTextOption *opt);

The 'GrTextRegion' structure and its associated functions can be used to
implement a fast (as much as possible in graphics modes) rectangular text
window using a fixed font. Clipping for such windows is done in character size
increments instead of pixels (i.e. no partial characters are drawn). Only
fixed fonts can be used in their natural size. 'GrDumpText' will cache the
code of the drawn characters in the buffer pointed to by the 'backup' slot (if
it is non-NULL) and will draw a character only if the previously drawn
character in that grid element is different. This can speed up text scrolling
significantly in graphics modes. The supported text types are the same as
above.

typedef struct {
GrFont *txr_font; /* font to be used */
char *txr_buffer; /* pointer to text buffer */
char *txr_backup; /* optional backup buffer */
int txr_xpos; /* upper left corner X coordinate */
int txr_ypos; /* upper left corner Y coordinate */


LIBGRX graphics library user's manual 20


int txr_width; /* width of area in chars */
int txr_height; /* height of area in chars */
int txr_lineoffset; /* offset in buffer(s) between lines */
union {
int v; /* color when no attributes */
GrColorTableP p; /* ptr to color table otherwise */
} txr_fgcolor,txr_bgcolor; /* foreground, background */
char txr_chrtype; /* character type (see above) */
} GrTextRegion;

void GrDumpChar(int chr,int col,int row,const GrTextRegion *r);
void GrDumpText(int col,int row,int wdt,int hgt,const GrTextRegion *r);
void GrDumpTextRegion(const GrTextRegion *r);

The 'GrDumpTextRegion' function outputs the whole text region, while
'GrDumpText' draws only a user-specified part of it. 'GrDumpChar' updates the
character in the buffer at the specified location with the new character
passed to it as argument and then draws the new character on the screen as
well.


Drawing in user coordinates

There is a second set of the graphics primitives which operates in user
coordinates. Every context has a user to screen coordinate mapping associated
with it. An application specifies the user window by calling the
'GrSetUserWindow' function.

void GrSetUserWindow(int x1,int y1,int x2,int y2);

A call to this function it in fact specifies the virtual coordinate limits
which will be mapped onto the current context regardless of the size of the
context. For example, the call:

GrSetUserWindow(0,0,11999,8999);

tells the library that the program will perform its drawing operations in a
coordinate system X:0...11999 (width = 12000) and Y:0...8999 (height = 9000).
This coordinate range will be mapped onto the total area of the current
context. The virtual coordinate system can also be shifted. For example:

GrSetUserWindow(5000,2000,16999,10999);

The user coordinates can even be used to turn the usual left-handed coordinate
system (0:0 corresponds to the upper left corner) to a right handed one (0:0
corresponds to the bottom left corner) by calling:

GrSetUserWindow(0,8999,11999,0);


LIBGRX graphics library user's manual 21


The library also provides three utility functions for the query of the
current user coordinate limits and for converting user coordinates to screen
coordinates and vice versa.

void GrGetUserWindow(int *x1,int *y1,int *x2,int *y2);
void GrGetScreenCoord(int *x,int *y);
void GrGetUserCoord(int *x,int *y);

If an application wants to take advantage of the user to screen
coordinate mapping it has to use the user coordinate version of
the graphics primitives. These have exactly the same parameter
passing conventions as their screen coordinate counterparts.
NOTE: the user coordinate system is not initialized by the
library! The application has to set up its coordinate mapping
before calling any of the use coordinate drawing functions --
otherwise the program will almost certainly exit (in a quite
ungraceful fashion) with a 'division by zero' error. The list of
supported user coordinate drawing functions:

void GrUsrPlot(int x,int y,int c);
void GrUsrLine(int x1,int y1,int x2,int y2,int c);
void GrUsrHLine(int x1,int x2,int y,int c);
void GrUsrVLine(int x,int y1,int y2,int c);
void GrUsrBox(int x1,int y1,int x2,int y2,int c);
void GrUsrFilledBox(int x1,int y1,int x2,int y2,int c);
void GrUsrFramedBox(int x1,int y1,int x2,int y2,int wdt,GrFBoxColors *c);
void GrUsrCircle(int xc,int yc,int r,int c);
void GrUsrEllipse(int xc,int yc,int xa,int ya,int c);
void GrUsrCircleArc(int xc,int yc,int r,int start,int end,int c);
void GrUsrEllipseArc(int xc,int yc,int xa,int ya,int start,int end,int c);
void GrUsrFilledCircle(int xc,int yc,int r,int c);
void GrUsrFilledEllipse(int xc,int yc,int xa,int ya,int c);
void GrUsrFilledCircleArc(int xc,int yc,int r,int start,int end,int c);
void GrUsrFilledEllipseArc(int xc,int yc,int xa,int ya,int start,int end,int c);
void GrUsrPolyLine(int numpts,int points[][2],int c);
void GrUsrPolygon(int numpts,int points[][2],int c);
void GrUsrFilledConvexPolygon(int numpts,int points[][2],int c);
void GrUsrFilledPolygon(int numpts,int points[][2],int c);
int GrUsrPixel(int x,int y);

void GrUsrCustomLine(int x1,int y1,int x2,int y2,const GrLineOption *o);
void GrUsrCustomBox(int x1,int y1,int x2,int y2,const GrLineOption *o);
void GrUsrCustomCircle(int xc,int yc,int r,const GrLineOption *o);
void GrUsrCustomEllipse(int xc,int yc,int xa,int ya,const GrLineOption *o);
void GrUsrCustomCircleArc(int xc,int yc,int r,int start,int end,const GrLineOption *o);
void GrUsrCustomEllipseArc(int xc,int yc,int xa,int ya,int start,int end,const GrLineOption *o);
void GrUsrCustomPolyLine(int numpts,int points[][2],const GrLineOption *o);
void GrUsrCustomPolygon(int numpts,int points[][2],const GrLineOption *o);

void GrUsrPatternedPlot(int x,int y,GrPattern *p);
void GrUsrPatternedLine(int x1,int y1,int x2,int y2,GrLinePattern *lp);


LIBGRX graphics library user's manual 22


void GrUsrPatternedBox(int x1,int y1,int x2,int y2,GrLinePattern *lp);
void GrUsrPatternedCircle(int xc,int yc,int r,GrLinePattern *lp);
void GrUsrPatternedEllipse(int xc,int yc,int xa,int ya,GrLinePattern *lp);
void GrUsrPatternedCircleArc(int xc,int yc,int r,int start,int end,GrLinePattern *lp);
void GrUsrPatternedEllipseArc(int xc,int yc,int xa,int ya,int start,int end,GrLinePattern *lp);
void GrUsrPatternedPolyLine(int numpts,int points[][2],GrLinePattern *lp);
void GrUsrPatternedPolygon(int numpts,int points[][2],GrLinePattern *lp);

void GrUsrPatternFilledBox(int x1,int y1,int x2,int y2,GrPattern *p);
void GrUsrPatternFilledCircle(int xc,int yc,int r,GrPattern *p);
void GrUsrPatternFilledEllipse(int xc,int yc,int xa,int ya,GrPattern *p);
void GrUsrPatternFilledCircleArc(int xc,int yc,int r,int start,int end,GrPattern *p);
void GrUsrPatternFilledEllipseArc(int xc,int yc,int xa,int ya,int start,int end,GrPattern *p);
void GrUsrPatternFilledConvexPolygon(int numpts,int points[][2],GrPattern *p);
void GrUsrPatternFilledPolygon(int numpts,int points[][2],GrPattern *p);

GrTextOption *GrUsrFindBestFont(int width,int height,int magnify,char *family,GrTextOption *where);
void GrUsrDrawChar(int chr,int x,int y,const GrTextOption *opt);
void GrUsrDrawString(char *text,int length,int x,int y,const GrTextOption *opt);
void GrUsrTextXY(int x,int y,char *text,int fg,int bg);


Graphics cursors

The library provides support for the creation and usage of an unlimited
number of graphics cursors. An application can use these cursors for any
purpose. Cursors always save the area they occupy before they are drawn. When
moved or erased they restore this area. As a general rule of thumb, an
application should erase a cursor before making changes to an area it occupies
and redraw the cursor after finishing the drawing. All cursor and mouse
related declaration are in the include file "mousex.h". Cursors are created
with the 'GrBuildCursor' function:

GrCursor *GrBuildCursor(char *data,int w,int h,int xo,int yo,const GrColorTableP c);

The 'data', 'w' (=width), 'h' (=height) and 'c' (= color table) arguments are
similar to the arguments of the pixmap building library function:
'GrBuildPixmap'. (See that paragraph for a more detailed explanation.) The
only difference is that the pixmap data is interpreted slightly differently:
any pixel with value zero is taken as a "transparent" pixel, i.e. the
background will show through the cursor pattern at that pixel. A pixmap data
byte with value = 1 will refer to the first color in the table, and so on. The
'xo' (= X offset) and 'yo' (= Y offset) arguments specify the position (from
the top left corner of the cursor pattern) of the cursor's "hot point". The
'GrCursor' data structure:


LIBGRX graphics library user's manual 23


typedef struct {
GrVidRAM cr_andmask; /* cursor bitmap to AND */
GrVidRAM cr_ormask; /* cursor bitmap to OR */
GrVidRAM cr_work; /* work area */
GrVidRAM cr_save; /* screen save area */
int cr_xcord,cr_ycord; /* cursor position on screen */
int cr_xsize,cr_ysize; /* cursor size */
int cr_xoffs,cr_yoffs; /* LU corner to hot point offset */
int cr_xwork,cr_ywork; /* save/work area sizes */
int cr_xwpos,cr_ywpos; /* save/work area position on screen */
int cr_displayed; /* set if displayed */
} GrCursor;

is typically not used (i.e. read or changed) by the application program, it
should just pass pointers to these structures to the appropriate library
functions. Other cursor manipulation functions:

void GrDestroyCursor(GrCursor *cursor);
void GrDisplayCursor(GrCursor *cursor);
void GrEraseCursor(GrCursor *cursor);
void GrMoveCursor(GrCursor *cursor,int x,int y);


Mouse event handling

All mouse services need the presence of a mouse and an installed
Microsoft compatible mouse driver. An application can test whether a mouse is
available by calling the function:

int MouseDetect(void);

which will return zero if no mouse (or mouse driver) is present, non-zero
otherwise. If the mouse is present the application may decide if it wants to
use the mouse in interrupt-driven or polled mode. The polled mode is
compatible with previous releases of DJGPP and the 256 color graphics library,
it uses the mouse driver interrupts (INT 33h) to query the mouse about its
position and buttons. This method is adequate if the program can do the
polling in a tight enough loop. If the program does lengthy computations in
the background during which a "frozen" mouse and the loss of mouse button
presses would be disturbing it has to use the interrupt driven method. For
this a patched version of GO32 is needed -- a GO32 version dated after the
middle of April 1992 should work. The interrupt driven mouse event mechanism
uses an event queue library (described in the document "EVENTS.DOC") which
stores all user interaction events (mouse presses and keyboard hits) in a
queue, timestamped, in the order of occurrence. The disadvantage of the
interrupt-driven mouse event mechanism is that it may be harder to debug. To
select between the two modes the following function needs to be called:

void MouseEventMode(int use_interrupts);


LIBGRX graphics library user's manual 24


If the 'use_interrupts' parameter is zero the mouse is put into polled mode
(this is the default), otherwise it will work interrupt-driven. After
selecting the mode, the mouse can be initialized by calling:

void MouseInit(void);

It is not necessary to call this function as the first call the
'MouseGetEvent' (see later) function will also perform the initialization.
However, if the mouse event mode is changed after using 'MouseGetEvent', a
call to 'MouseInit' is the only way to enforce the change.

If the mouse is used in interrupt-driven mode, it is a good practice to
call 'MouseUnInit' before exiting the program. This will restore any interrupt
vectors hooked by the program to their original values.

void MouseUnInit(void);

The mouse can be controlled with the following functions:

void MouseSetSpeed(int speed);
void MouseSetAccel(int thresh,int accel);
void MouseSetLimits(int x1,int y1,int x2,int y2);
void MouseGetLimits(int *x1,int *y1,int *x2,int *y2);
void MouseWarp(int x,int y);

The library calculates the mouse position only from the mouse mickey counters.
(To avoid the limit and 'rounding to the next multiple of eight' problem with
the Microsoft mouse driver when it finds itself in a graphics mode unknown to
it.) The 'speed' parameter to the 'MouseSetSpeed' function is used as a
divisor, i.e. coordinate changes are obtained by dividing the mickey counter
changes by this value. In high resolution graphics modes the value of one just
works fine, in low resolution modes (320x200 or similar) it is best set the
speed to two or three. (Of course, it also depends on the sensitivity the
mouse.) The 'MouseSetAccel' function is used to control the ballistic effect:
if a mouse coordinate changes between two samplings by more than the 'thresh'
parameter, the change is multiplied by the 'accel' parameter. NOTE: some mouse
drivers perform similar calculations before reporting the coordinates in
mickeys. In this case the acceleration done by the library will be additional
to the one already performed by the mouse driver. The limits of the mouse
movement can be set (passed limits will be clipped to the screen) with
'MouseSetLimits' (default is the whole screen) and the current limits can be
obtained with 'MouseGetLimits'. 'MouseWarp' sets the mouse cursor to the
specified position.

As typical mouse drivers do not know how to draw mouse cursors in high
resolution graphics modes, the mouse cursor is drawn by the library. The mouse
cursor can be set with:

void MouseSetCursor(GrCursor *cursor);
void MouseSetColors(int fg,int bg);


LIBGRX graphics library user's manual 25


'MouseSetColors' uses an internal arrow pattern, the color 'fg' will be used
as the interior of it and 'bg' will be the border. The current mouse cursor
can be obtained with:

GrCursor *MouseGetCursor(void);

The mouse cursor can be displayed/erased with:

void MouseDisplayCursor(void);
void MouseEraseCursor(void);

The mouse cursor can be left permanently displayed. All graphics primitives
except for the few non-clipping functions check for conflicts with the mouse
cursor and erase it before the drawing if necessary. Of course, it may be more
efficient to erase the cursor manually before a long drawing sequence and
redraw it after completion. The library provides an alternative pair of calls
for this purpose which will erase the cursor only if it interferes with the
drawing:

int MouseBlock(GrContext *c,int x1,int y1,int x2,int y2);
void MouseUnBlock(void);

'MouseBlock' should be passed the context in which the drawing will take place
(the usual convention of NULL meaning the current context is supported) and
the limits of the affected area. It will erase the cursor only if it
interferes with the drawing. If it returns a non-zero value then
'MouseUnBlock' has to be called at the end of the drawing, otherwise it should
not be called.

The library supports (beside the simple cursor drawing) three types of
"rubberband" attached to the mouse cursor. The 'MouseSetCursorMode' function
is used to select the cursor drawing mode.

void MouseSetCursorMode(int mode,...);

The parameter 'mode' can have the following values:

/*
* MOUSE CURSOR modes:
* M_CUR_NORMAL -- just the cursor
* M_CUR_RUBBER -- rectangular rubber band (XOR-d to the screen)
* M_CUR_LINE -- line attached to the cursor
* M_CUR_BOX -- rectangular box dragged by the cursor
*/
#define M_CUR_NORMAL 0
#define M_CUR_RUBBER 1
#define M_CUR_LINE 2
#define M_CUR_BOX 3

'MouseSetCursorMode' takes different parameters depending on the cursor
drawing mode selected. The accepted call formats are:


LIBGRX graphics library user's manual 26


MouseSetCursorMode(M_CUR_NORMAL);
MouseSetCursorMode(M_CUR_RUBBER,xanchor,yanchor,color);
MouseSetCursorMode(M_CUR_LINE,xanchor,yanchor,color);
MouseSetCursorMode(M_CUR_BOX,dx1,dy1,dx2,dy2,color);

The anchor parameters for the rubberband and rubberline modes specify a fixed
screen location to which the other corner of the primitive is bound. The 'dx1'
through 'dy2' parameters define the offsets of the corners of the dragged box
from the hotpoint of the mouse cursor. The color value passed is always XOR-ed
to the screen, i.e. if an application wants the rubberband to appear in a
given color on a given background then it has to pass the XOR of these two
colors to 'MouseSetCursorMode'.

The status of the mouse cursor can be obtained with calling
'MouseCursorIsDisplayed'. This function will return non-zero if the cursor is
displayed, zero if it is erased.

int MouseCursorIsDisplayed(void);

The 'MouseGetEvent' function is used to obtain the next mouse or
keyboard event. It takes a flag with various bits encoding the type of event
needed. It returns the event in a 'MouseEvent' structure. The relevant
declarations from "mousex.h":

void MouseGetEvent(int flags,MouseEvent *event);

typedef struct {
int flags; /* flags (see above) */
int x,y; /* coordinates */
int buttons; /* button state */
int key; /* key code from keyboard */
int kbstat; /* keybd status (ALT, CTRL, etc..) */
long time; /* time stamp of the event */
} MouseEvent;

The event structure has been extended with a keyboard status word (thus a
program can check for combinations like ALT-<left mousebutton press>) and a
time stamp (in DOS clock ticks since the start of the program) which can be
used to check for double clicks, etc... The following macros have been defined
in "mousex.h" to help in creating the control flag for 'MouseGetEvent' and
decoding the various bits in the event structure:

/*
* MOUSE event flag bits
*/
#define M_MOTION 0x001
#define M_LEFT_DOWN 0x002
#define M_LEFT_UP 0x004
#define M_RIGHT_DOWN 0x008
#define M_RIGHT_UP 0x010
#define M_MIDDLE_DOWN 0x020


LIBGRX graphics library user's manual 27


#define M_MIDDLE_UP 0x040
#define M_BUTTON_DOWN (M_LEFT_DOWN | M_MIDDLE_DOWN | M_RIGHT_DOWN)
#define M_BUTTON_UP (M_LEFT_UP | M_MIDDLE_UP | M_RIGHT_UP)
#define M_BUTTON_CHANGE (M_BUTTON_UP | M_BUTTON_DOWN )

/*
* MOUSE button status bits
*/
#define M_LEFT 1
#define M_RIGHT 2
#define M_MIDDLE 4

/*
* Other bits and combinations
*/
#define M_KEYPRESS 0x080 /* keypress */
#define M_POLL 0x100 /* do not wait for the event */
#define M_NOPAINT 0x200
#define M_EVENT (M_MOTION | M_KEYPRESS | M_BUTTON_DOWN | M_BUTTON_UP)

/*
* KEYBOARD status word bits
*/
#define KB_RIGHTSHIFT 0x01 /* right shift key depressed */
#define KB_LEFTSHIFT 0x02 /* left shift key depressed */
#define KB_CTRL 0x04 /* CTRL depressed */
#define KB_ALT 0x08 /* ALT depressed */
#define KB_SCROLLOCK 0x10 /* SCROLL LOCK active */
#define KB_NUMLOCK 0x20 /* NUM LOCK active */
#define KB_CAPSLOCK 0x40 /* CAPS LOCK active */
#define KB_INSERT 0x80 /* INSERT state active */

#define KB_SHIFT (KB_LEFTSHIFT | KB_RIGHTSHIFT)

'MouseGetEvent' will display the mouse cursor if it was previously erased and
the 'M_NOPAINT' bit is not set in the flag passed to it. In this case it will
also erase the cursor after an event has been obtained.

NOTE: some of the mouse event constants have different values than in the
original DJGPP graphics library. This change was necessary to better follow
the mouse driver conventions for assigning bits with similar functions.

The generation of mouse and keyboard events can be individually enabled or
disabled (by passing a non-zero or zero, respectively, value in the
corresponding 'enable_XX' parameter) by calling:

void MouseEventEnable(int enable_kb,int enable_ms);


README for GRX 1.03 beta release
================================

This is file README.GRX. It can be found at the beta7 distribution site
and also in the DOCS sub-directory of the GRX archive. This file contains
additional information about the new graphics-related features of GO32,
the new graphics drivers and GRX 1.03.

What is in this release?
------------------------

This is an intermediate release based on my working sources. This version
does not yet work with DPMI. On the other hand, it has been modified to work
with the new (.VDR) drivers. These drivers together with the modifications
in GO32 1.11 allow the use of more than 1MB of video RAM. Virtual screens
larger than the displayed screen are also supported, together with a GO32
function to change the start of the displayed region (pan). The beta GO32
1.11 already has a new format built-in VESA driver.

This version only supports display modes which were present in GRX 1.02.
(I.e. 16, 256, 32K colors and accelerated S3/8514A 256 color modes.) I don't
intend to finish the missing display modes in the current page-fault based
video RAM access mode. Currently I am working on a new set of low-level GRX
video RAM access routines which will use explicit paging. These will support
DPMI graphics with >64K frame buffers. As soon as these are finished and
tested there will be another GRX release.

The other new feature of this release is that all thick and patterned
line primitives (which were missing from GRX 1.02) are present in this
version.

New driver interface
--------------------

The format of the VDR drivers can be found in the "grdriver.h" file in
the GO32 source directory or in the NDRIVERS directory of the GRX archive.
The built-in driver in GO32 should work with any VESA compatible SVGA card.
Older (.GRD or .GRN) drivers still work with the new GO32 and graphics
library. There is a small change in the driver specification part of the
GO32 environment variable:

SET GO32=driver <driver_name>::<driver_options> tw ...
				 ^^^^^^^^^^^^^^^^^^
				 new fields

If the name of the driver is followed by two colons and a string then this
string is taken as an option string for the driver. GO32 configures the driver
according to the characters in this string when the driver is loaded. (Which
now happens only when the driver is first used.) The option string is
ignored for .GRD and .GRD drivers.

The option string can contain the following characters (in any order, case
does not matter):

p:	Enables protected mode paging. For .VDR drivers the default is to use
	the driver's paging function in real mode. This is necessary because
	the VESA BIOS paging function was written for real mode. However, many
	VESA BIOS-es are well written, and their paging function can be used
	in protected mode. Give it a try, if it fails then you have to use
	real mode paging which is MUCH slower. (paging with .GRD and .GRN
	drivers is always in protected mode)

f:	Enables fast 256 color mode. On some SVGA cards the planar, mode X-like
	256 color memory organization can be used even in SVGA modes. There are
	a few operations (especially horizontal scan line fills) which can
	be much faster in this mode. Give it a try -- and if you see garbage
	on the screen then it does not work with your card.

5:	This field is necessary only if your VESA BIOS is version 1.1 or older
	and the 64K (16 bit) color mode reported by it is really only a 32K
	(15 bit) mode. You can find out your VESA version number and a lot of
	other VESA related stuff by running the VESAINFO program in the
	NDRIVERS directory of the GRX archive.

If you want to use the built-in GO32 driver with options use the following
syntax:

	SET GO32 = driver ::pf5 tw ...

When using a new .VDR driver with GO32 1.11 the video memory is mapped as
follows:

	0xd0000000 .. 0xd0100000	old 1MB RW area
	0xd0100000 .. 0xd0200000	old 1MB R0 area
	0xd0200000 .. 0xd0300000	old 1MB W0 area

	0xd1000000 .. 0xd2000000	new 16MB RW area
	0xd2000000 .. 0xd3000000	new 16MB R0 area
	0xd3000000 .. 0xd4000000	new 16MB W0 area

GRX 1.03 uses the 1MB areas whenever the frame buffer is less then 1MB,
otherwise it uses the 16MB areas.

GO32 1.11 supports the following new int 0x10 calls:

Mode set with virtual screen sizes:
Input:
ax = 10		 // = GR_custom_graphics
bx = colors
cx = desired screen width
dx = desired screen height
VDR_driver_header.virtual_x = desired virtual width
VDR_driver_header.virtual_y = desired virtual heigth
Output:
bx = mode descriptor bits
cx = actual screen width
dx = actual screen height
VDR_driver_header.virtual_x = actual virtual width
VDR_driver_header.virtual_y = actual virtual heigth

Inquire driver header linear address:
Input:
ax = 0xfffe
Output:
eax = linear address of driver header in real memory. (Add 0xe0000000
	 when used in non-DPMI modes of the extender). Use this buffer
	 for passing the virtual screen parameters to the driver.

Call driver paging function in real mode:
Input:
ax = 0xfffd
bl = read page
bh = write page
Output: none

Set displayed screen start when virtual screen > displayed screen
Input:
ax = 0xfffc
cx = X position
dx = Y position
Output: none