/*------------------------ VIS_COMP.TXT ------------------------*/ /* */ /* This file contains the VISIONS Compiler Specific */ /* Library Manual */ /* */ /* Copyright 1990 Dan Vogel & David Bernazzani */ /* */ /* Date Initials Comments */ /* */ /* 12/04/90 DCV Initial Release 0.00. */ /*--------------------------------------------------------------*/ Overview The VISIONS compiler specific code library consists of routines that are highly specific to the compiler being used, as well as some routines that just do not fit in anywhere else. There are five groups of routines in this library: video routines, keyboard routines, interrupt interface routines, background procedure support, and a time delay routine. This implementation of the compiler specific library was written using Microsoft C 5.1, and is entirely written in C. The compiler specific library supports the following functions: Screen Clears Vertical Scrolling Get Video Mode Keystrike Detection Set Video Mode Keyboard Reads Hide and Restore Text Cursor BIOS Keyboard Service Interface Wrap Control Interrupt Interface Set Windows Vector Reads Specify Screen Size Memory Storage Pointer Services Color Control Timed Delay Loops Text String Display Background Procedure Support Theory of Operation The compiler specific library does not have a unified theory of operation in that it is intended primarily to isolate functions that may be compiler specific. The only major interactions between the individual functions is that the video display functions interact to save the expected current state of the display for video output, and the keyboard routines must support the background procedure execution. For example the window origin and sizes that are set are stored internally to allow the text output routine to clip text that goes beyond the window boundaries. Another example is the keyboard routine interactions with the background procedure support. The background procedure is a routine installed by the user, through the Comp_InstallBkProc call, that will be executed whenever VISIONS is awaiting a keystroke. This is accomplished by having Comp_Kbhit call the background procedure, through the Comp_ExecuteBkProc call, while it is waiting for a keystroke. Since all VISIONS libraries (MENU, FORM etc.) use this routine directly or indirectly for reading the keyboard, the background procedure can be assured of being executed while the system awaits user input. Routine Definitions In order to use the below routines you must include the file "USERCOMP.H" in your source code with the following statement. #include "USERCOMP.H" Specific examples of the use of these routines are not currently available, although they are used through the demonstration programs and within the VISIONS windows libraries. If you are compiling a program written for VISIONS 1.0 and do not wish to modify the routine names in your source, add the following statement to provide name conversions. #include "COMPCONV.H" /*------------------------------------------------------------------------*/ Comp_BiosKeybrd Purpose: This routine provides an interface to the BIOS keyboard services. Calling Sequence: ret = Comp_BiosKeybrd(service); Inputs: WORD service; - This is the BIOS keyboard service requested. Possible values are: KEYB_READ - Read Keyboard. KEYB_READY - Keyboard Ready. KEYB_SHIFT - Keyboard shift Status. Outputs: WORD ret; - For a keyboard read this is the character read from the keyboard in the low byte, or if zero, the high byte contains the scan code. If this is a keyboard ready, a zero return means no key ready, otherwise the key is returned in the same format as a keyboard read. A shift status call returns only the low byte with the following bit meanings: Bit Meaning if true- 0 Right-most shift key 1 Left-most shift key 2 CTRL key 3 ALT key 4 SCROLL LOCK on 5 NUM LOCK on 6 CAPS LOCK on 7 INS mode on Functions called: Comp_Kbhit. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_ClearScreen Purpose: This routine clears an area of the screen and fills that area with the default background color. Calling Sequence: Comp_ClearScreen(area); Inputs: WORD area; - This is the area to be filled. Possible values are: CLEAR_WINDOW - fill the currently defined text window. CLEAR_VIEWPORT - fill the current viewport. CLEAR_SCREEN - clear and fill the entire screen. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_Delay Purpose: This is a code loop delay routine that self-calibrates to delay approximately the number of passed millisecond ticks. Accuracy should only be about +-30% (for larger number of delays...). Calling this routine with a parameter of -1 generates a calibration pass which will cause a delay of between 3 and 12 seconds. Thereafter the calls are calibrated. If the calibration call is not made, the delays will not be calibrated to the machine speed, hence the delays will be proportional but not accurate. Calling Sequence: Comp_Delay(ticks); Inputs: WORD ticks; - This is a measure of the length of delay desired. This is not an exact measurement but should approximate milliseconds with about +-33% accuracy for larger values. A value of -1 causes a calibration pass, as opposed to a timed delay. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_ExecuteBkProc Purpose: This routine executes the pre-defined background procedure. If no procedure has been installed, then this routine returns immediately. Calling Sequence: Comp_ExecuteBkProc(); Inputs: None. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_GetKey Purpose: This routine reads the keyboard. All multicharacter keys (like up arrow) are converted to 128 + value of second character. Thus all keys are mapped into a single byte. Calling Sequence: key = Comp_GetKey(); Inputs: None. Outputs: UWORD *key; - This is the token read from the keyboard. Functions called: Comp_BiosKeybrd. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_GetAnyKey Purpose: This routine waits for either a keystroke or a mouse button push before returning to the caller. Mouse button pushes are returned as -1, while keystrokes return the value entered. Calling Sequence: key = Comp_GetAnyKey(); Inputs: None. Outputs: UWORD *key; - This is the token read from the keyboard, or -1 if a mouse button was pressed. Functions called: Comp_GetKey, Mouse_ClearButtons, Mouse_GetButtonPress. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_GetOffset Purpose: This routine returns the offset of the passed integer pointer as a 16 bit UWORD. Calling Sequence: offset = Comp_GetOffset(&val); Inputs: UWORD *val; - This is a pointer to an integer variable (other types may be used and cast) whose offset is to be returned. Outputs: UWORD offset; - This is the offset of the passed pointer. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_GetSegment Purpose: This routine returns the segment pointer of the passed integer pointer as a 16 bit unsigned integer. Calling Sequence: seg = Comp_GetSegment(&val); Inputs: UWORD *val; - This is a pointer to an integer variable (other types may be used and cast) whose segment is to be returned. Outputs: UWORD seg; - This is the segment of the passed pointer. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_GetVector Purpose: This routine returns the far pointer to the interrupt routine stored as the passed interrupt vector number handler. Calling Sequence: int_ptr = Comp_GetVector(&vec); Inputs: UWORD vec; - This is the vector number whose interrupt routine pointer is to be returned. Outputs: VOID far *int_ptr(); - This is the pointer to the interrupt routine. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_GetVideoInfo Purpose: This routine gets the current video information including adapter type, monitor type, and display mode. Calling Sequence: status = Comp_GetVideoInfo(&adapter, &monitor, &mode, &segaddr); Inputs: None. Outputs: UWORD far * *segaddr; - This is the segment address of the video RAM for this mode. WORD *adapter; - This is the type of video adapter in use. Possible values are: 0 MPDA Monochrome Display Adapter 1 CGA Color Graphics Adapter 2 EGA Enhanced Graphics Adapter 3 VGA Video Graphics Array 4 MCGA MultiColor Graphics Array 5 HGC Hercules Graphics Card WORD *monitor; - This is the monitor type in use. Possible values are: 0 MONO Monochrome 1 COLOR Color or enhanced emulating color 2 ENHCOLOR Enhanced Color 3 ANALOG Analog WORD *mode; - This is the mode the adapter is set. Possible values are: 0 TEXTBW40 40 x 25 text, 16 grey 1 TEXTC40 40 x 25 text, 16/8 color 2 TEXTBW80 80 x 25 text, 16 grey 3 TEXTC80 80 x 25 text, 16/8 color 4 MRES4COLOR 320 x 200, 4 color 5 MRESNOCOLOR 320 x 200, 4 grey 6 HRESBW 640 x 200, BW 7 TEXTMONO 80 x 25 text, BW 8 HERCMONO 720 x 348, BW for HGC 13 MRES16COLOR 320 x 200, 16 color 14 HRES16COLOR 640 x 200, 16 color 15 ERESNOCOLOR 640 x 350, BW 16 ERESCOLOR 640 x 350, 4 or 16 color 17 VRES2COLOR 640 x 480, BW 18 VRES16COLOR 640 x 480, 16 color 19 MRES256COLOR 320 x 200, 256 color WORD status; - This is the result of the function. Possible values are: COMP_ERR_NO_ERR Success COMP_ERR_UNKNOWN_STATE State of adaptor and monitor is not recognized Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_InstallBkProc Purpose: This routine installs the passed routine pointer as the background process. Note that background procedures written by the user must not attempt to read the keyboard, nor may they call any routines requiring the keyboard! Calling Sequence: Comp_InstallBkProc(proc); Inputs: proc - WORD (*)(VOID) - This is the procedure, or NULL, to be installed. Passing NULL de-installs the current procedure. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_Interrupt86 Purpose: This routine provides a partial interface to the microprocessor software interrupt capabilities in the BIOS. By partial interface, we mean that this routine can specify only the interrupt number desired, and the values for the AH and CX register. The return value is the return value of the interrupt, other registers returned by the interrupt are lost. Calling Sequence: status = Comp_Interrupt86 (intno, &axreg, &bxreg, &cxreg, &dxreg, &sireg, &direg); Inputs: WORD intno; - This is the desired software interrupt number. UWORD *axreg, to *direg; - These are pointers to the values to be placed in the registers prior to the interrupt, and also where the return values are to be placed. Outputs: WORD status; - This is the value returned by the interrupt in the AX register. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_Interrupt86ext Purpose: This routine provides a full interface to the microprocessor software interrupt capabilities in the BIOS. Calling Sequence: status = Comp_Interrupt86ext (intno, &axreg, &bxreg, &cxreg, &dxreg,&sireg, &direg, &dsreg, &esreg); Inputs: WORD intno; - This is the desired software interrupt number. WORD *axreg, to *esreg; - These are pointers to the values to be placed in the registers prior to the interrupt, and also where the return values are to be placed. Outputs: WORD status; - This is the value returned by the interrupt in the AX register. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_Kbhit Purpose: This routine checks the keyboard to see if a key has been struck. Calling Sequence: status = Comp_Kbhit(); Inputs: None. Outputs: FLAG status; - This is FALSE if no key has been pressed, otherwise TRUE. Functions called: Comp_ExecuteBkProc. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_ModifyColors Purpose: This routine modifies the text as well as the background colors of a specified area of the screen. Calling Sequence: status = Comp_ModifyColors(row, col, height, width, txtcol_mask, txtcol, bkcol_mask, bkcol); Inputs: UBYTE row, col; - These are the coordinates of the top left corner of the window to be modified. Valid values range from 1,1 to n,m. UBYTE height, width; - These are the height and width of the desired window. DWORD txtcol_mask, bkcol_mask; - These are the masks of the colors bits to be affected by the color changes. Only the 4 LSBs of each parameter is currently used. Normal values are 0, meaning no change, or 0xff, meaning change to passed color. Other values will allow true masking of individual bits of the color specifiers. DWORD txtcol, bkcol; - These are the colors to be ORed into the specified screen area. Possible values are: BLACK 0 BLUE 1 GREEN 2 CYAN 3 RED 4 MAGENTA 5 BROWN 6 WHITE 7 DARK GREY 8 LIGHT BLUE 9 LIGHT GREEN 10 LIGHT CYAN 11 LIGHT RED 12 LIGHT MAGENTA 13 YELLOW 14 BRIGHT WHITE 15 Outputs: WORD status; - This is the result of the function. Possible values are: COMP_ERR_NO_ERR Success COMP_ERR_BAD_COORD Coordinates are off screen Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_OutText Purpose: This routine outputs a string of characters to the current text position in the window on the display. Calling Sequence: Comp_OutText(msg); Inputs: TEXT *msg; - This is the array of characters, terminated by a NULL, to be displayed at the current text location using the defined background and text colors. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_SetBkColor Purpose: This routine sets the default background color for the window in use, or any future window, until such time as the background color is again changed via this routine. Calling Sequence: status = Comp_SetBkColor(bkcol); Inputs: WORD bkcol; - This is the background color to be set. Possible values are: Graphics Mode: Text Mode: BLACK 000000H BLACK 0 BLUE 2A0000H BLUE 1 GREEN 002A00H GREEN 2 CYAN 2A2A00H CYAN 3 RED 00002AH RED 4 MAGENTA 2A002AH MAGENTA 5 BROWN 00152AH BROWN 6 WHITE 2A2A2AH WHITE 7 GRAY 151515H DARK GREY 8 LIGHT BLUE 3F1515H LIGHT BLUE 9 LIGHT GREEN 153F15H LIGHT GREEN 10 LIGHT CYAN 3F3F15H LIGHT CYAN 11 LIGHT RED 15153FH LIGHT RED 12 LIGHT MAGENTA 3F153FH LIGHT MAGENTA 13 LIGHT YELLOW 153F3FH YELLOW 14 BRIGHT WHITE 3F3F3FH BRIGHT WHITE 15 Note that these colors may vary dependent on controller, monitor, monitor settings, and pallette mappings! Outputs: DWORD status; - This is the background color setting prior to executing this call. Possible values are the same as the possible values for bkcol above. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_SetScreenRows Purpose: This routine allows the caller to set the display into either 25 or 43 text row mode. It is assumed upon entering this routine that the video mode required is set. This routine should only be called for EGA or VGA adaptors, but will return errors if not. Calling Sequence: status = Comp_SetScreenRows(rows); Inputs: UBYTE rows; - This is the number of rows requested for the display. Possible values are 25 and 43 (and 50 for VGA). Outputs: WORD status; - This is the result of the function. Possible values are: COMP_ERR_NO_ERR Success COMP_ERR_BAD_ROW Can not set adaptor and monitor to row size requested Functions called: Comp_GetVideoInfo, Comp_Interrupt86, Comp_TextCursor. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_SetTextColor Purpose: This routine sets the default color of text drawn for the window in use, or any future window, until such time as the text color is again changed via this routine. Calling Sequence: status = Comp_SetTextColor(txtcol); Inputs: DWORD txtcol; - This is the color to set the text color to. Possible values are: BLACK 0 BLUE 1 GREEN 2 CYAN 3 RED 4 MAGENTA 5 BROWN 6 WHITE 7 DARK GREY 8 LIGHT BLUE 9 LIGHT GREEN 10 LIGHT CYAN 11 LIGHT RED 12 LIGHT MAGENTA 13 YELLOW 14 BRIGHT WHITE 15 Note that these colors may vary with the adaptor used! Of special importance is the value of bit 4 of the color value, yielding a color range of 16 to 31. Setting this bit can cause the adaptor to blink the text using the color-15 as the color value. A different adaptor might underline the text, for the same value. Consult the manual for your adaptor, or a good reference book on video programming for more information. Outputs: DWORD status; - This is the value of the text color setting prior to this call. Possible values are the same as for txtcol above. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_SetTextPosition Purpose: This routine sets the position of the next text output to the current window, for that text displayed using OutText. The position specified is 1 based from the top left corner of the current window. Coordinates exceeding the boundaries of the current window produce undefined results. Calling Sequence: Comp_SetTextPosition(row, col); Inputs: UBYTE row, col; - These are the coordinates of the desired text position. The top left corner is position 1,1. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_SetTextWindow Purpose: This routine defines a window on the screen for text output. This window will then be subject to the specified default background and text colors during text output. Calling Sequence: Comp_SetTextWindow(row, col, height, width); Inputs: UBYTE row, col; - These are the coordinates of the top left corner of the desired window. Valid values range from 1,1 to n,m. UBYTE height, width; - These are the height and width of the desired window. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_SetVideoMode Purpose: This routine defines the video mode for the display adapter. Calling Sequence: status = Comp_SetVideoMode(mode, &segaddr); Inputs: WORD mode; - This is the mode to set the adapter to. Possible values are: DEFAULTMODE restore screen to original mode TEXTBW40 40 x 25 text, 16 grey TEXTC40 40 x 25 text, 16/8 color TEXTBW80 80 x 25 text, 16 grey TEXTC80 80 x 25 text, 16/8 color MRES4COLOR 320 x 200, 4 color MRESNOCOLOR 320 x 200, 4 grey HRESBW 640 x 200, BW TEXTMONO 80 x 25 text, BW HERCMONO 720 x 348, BW for HGC MRES16COLOR 320 x 200, 16 color HRES16COLOR 640 x 200, 16 color ERESNOCOLOR 640 x 350, BW ERESCOLOR 640 x 350, 4 or 16 color VRES2COLOR 640 x 480, BW VRES16COLOR 640 x 480, 16 color MRES256COLOR 320 x 200, 256 color Outputs: UWORD far * *segaddr; - This is the segment address of the video ram buffer. WORD status; - This is the result of the routine. Possible values are: COMP_ERR_NO_ERR Success COMP_ERR_BAD_MODE Unknown video mode COMP_ERR_MODE_FAILED Unable to set video to requested mode Functions called: Comp_GetVideoInfo. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_TextCursor Purpose: This routine turns off or on the display cursor, and saves the previous setting. Calling Sequence: Comp_TextCursor(on_off); Inputs: FLAG on_off; - This may be either ON or OFF to request the state of the cursor. Outputs: None. Functions called: Interrupt86. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_VertScroll Purpose: This routine scrolls a window of text up or down. Calling Sequence: Comp_VertScroll(top_row, left_col, height, width, direct, lines); Inputs: UBYTE top_row, left_col, height, width; - These are the coordinates of the window we are to scroll. UBYTE direct; - This is the direction of the scroll. Possible values are UP and DOWN. UBYTE line; - This is the number of lines to scroll the window in the specified direction. Outputs: None. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Comp_WrapOn Purpose: The WrapOn routine determines whether the text output to a window is clipped or wrapped around to the next line if it extends beyond the current line. Normally this will be set to clipped, as the resulting scrolling of the window in wrap mode can produce undesirable results, making the bottom rightmost character of a window unusable (if normal, non-direct output methods are used)! Calling Sequence: status = Comp_WrapOn(onoff); Inputs: FLAG onoff; - This value indicates if wrap is to be turned OFF, or ON. Outputs: FLAG status; - This is the value of the wrap setting prior to the call. Possible values are OFF, or ON. Functions called: None. /*------------------------------------------------------------------------*/ Error Codes The following is the list of error codes that can be returned from the VISIONS compiler specific library. Error Name Value Description. COMP_ERR_NO_ERR 0 Success COMP_ERR_BAD_MODE -500 Unknown video mode COMP_ERR_MODE_FAILED -501 Unable to set video to requested mode COMP_ERR_UNKNOWN_STATE -502 State of adaptor/monitor not recognized COMP_ERR_BAD_ROW -503 Can not set to row size requested COMP_ERR_BAD_COORD -504 Coordinates are off screen