Every DOS program that has any need for speed must write directly to the video screen memory. Our method is to replace the standard library version of the printf() function with our own. We also provide windowing, cursor positioning, colors, invisible screen-image updating (so that, for example, we can update both the main console and two channel emulation screens simultaneously), and a few other miscellaneous functions. All of these routines are available in the ??GCOMM.LIB files:
printf(ctlstg,p1,p2,...,pn);
substitute for standard printf()
char *ctlstg; control string, functions supported are %s,%c,%d,%u,%x, all of them with field length, zero or blank fill, left/right justification options
TYPE p1,p2,...,pn; just like printf/cprintf parms
(note: no longs or floats)
There is no limit to the number of parameters (p1,p2,...,pn) that you may pass to printf(). They should correspond one-for-one with the % directives in the control string. See page 270 for a description of the ANSI graphics capability of printf().
setatr(attrib); sets video attributes
int attrib; attribute code: sum of...
0x80 = blink foreground
0x40 = red background
0x20 = green background
0x10 = blue background
0x08 = bright foreground
0x04 = red foreground
0x02 = green foreground
0x01 = blue foreground
Another way to compute the attribute is to add together three numbers, one from each of these columns:
| Foreground Attribute + | Background Attribute + | Blink |
| 0x00 Black | 0x00 Black | 0x00 non-blinking |
| 0x01 Dark blue | 0x10 Dark blue | 0x80 blinking foreground |
| 0x02 Green | 0x20 Green | |
| 0x03 Cyan | 0x30 Cyan (blue-green) | |
| 0x04 Red | 0x40 Red | |
| 0x05 Magenta | 0x50 Magenta | |
| 0x06 Brown | 0x60 Brown | |
| 0x07 Grey | 0x70 Grey | |
| 0x08 Dark Grey | ||
| 0x09 Bright blue | ||
| 0x0A Bright green | ||
| 0x0B Bright cyan | ||
| 0x0C Bright red | ||
| 0x0D Bright magenta | ||
| 0x0E Bright yellow | ||
| 0x0F Bright white |
This function affects subsequent printf()s. You can change the background color of the entire screen, for example to magenta, by coding:
setatr(0x5E);
printf("\f");Then all subsequent printf()s will show bright yellow on magenta. The clreol() function also sets the background color for the remainder of the line according to the latest setatr() attribute.
See page 272 for converting IBM screen attribute codes into ANSI color coding sequences.
See page 299 for what setatr() does on monochrome screens.
setwin(scn,xul,yul,xlr,ylr,sen);
set window parameters
char *scn; seg:off start addr of screen (if NULL, default display)
int xul; upper left x coordinate
int yul; upper left y coordinate
int xlr; lower right x coordinate
int ylr; lower right y coordinate
int sen; scroll enable (1=yes)
rstwin(); restore previous window parameters
The setwin() function defines a window on the screen. All coordinates are inclusive (they are inside the window). The scn parameter can be used to direct all subsequent screen output to a SCNSIZ-byte buffer (SCNSIZ is 4000) instead of to the visible video memory. Make scn NULL for the default condition of writing directly to video memory. The sen parameter, when 1, means that when you printf() a newline (\n) on the last line of the window, the entire window gets scrolled up one line (and the bottom line is filled with the current setatr() background attribute). When sen is 0, then a newline has the same effect as a carriage return (\r) on the bottom line of the window. The rstwin() function undoes the effect of the most recent setwin() call.
scnstt=frzseg(); get video RAM base address
char *scnstt; segment:offset start address of screen
unfrez(); release video RAM address (in a multitasking environment).
Applies to: WG3.x
Header check:
unfrez()(WG2GCOMM.H:432) andclreol()(WG2GCOMM.H:438) are not declared in the WG3.2GCOMM.H/VIDAPI.H;frzseg()is (VIDAPI.H:25) andscn2mem/mem2scn/scn2scnare macros over it (VIDAPI.H:30-32).SCNSIZ(WG2GCOMM.H:231, 4000) is no longer defined.setatr()is still declared (VIDAPI.H:147;sstatris now the alias,GCOMM.H:140).
The frzseg() function returns a pointer to the physical video memory (or in some multitasking environments, to the “hidden” screen).
The unfrez() function releases the memory indicated by frzseg() (that is, the scnstt return value of frzseg() should not be used after calling unfrez()). This is only required in certain multitasking environments that permit writing directly to screen memory. Even so, since printf() calls both frzseg() and unfrez() (when the first parameter in the most recent call to setwin() was NULL), you may not need to call unfrez() at all — just wait until the next printf().
To blank out a SCNSIZ-byte screen buffer area:
scblank(buffer,attr); Blank the screen buffer memory
char *buffer; SCNSIZ-byte buffer (4000 bytes)
char attr; Attribute to use
2000 spaces with the specified attribute are written to the buffer.
scnstt=auxcrt(); get auxiliary CRT address
char *scnstt; pointer to auxiliary screen address
locate(x,y); move cursor to x,y
int x; dest x (0=left-most column)
int y; dest y (0=top line)
rstloc(); restore previous cursor location
x=curcurx(); get current cursor x coordinate
int x;
y=curcury(); get current cursor y coordinate
int y;
The locate() function moves the video cursor to a new location. Even if setwin() has directed video output to an invisible buffer, the visible cursor may still move to track the locate() function (see cursact() below). The rstloc() function undoes the effect of the most recent locate() call. All cursor positions are relative to the upper left corner of the display buffer (not to the upper left corner of the setwin() window).
clreol(); clear to end of line (in window)
This function clears from the cursor position to the right margin of the current window, setting the background attribute for this line segment to the current setatr() attribute.
printfat(x,y,ctlstg,p1,...,pn);
combination of locate() and printf() into one routine (saves code space)
int x,y; screen coordinates
char *ctlstg; control string
p1,...,pn parameters (max 8 bytes)
This routine is like printf(), except that the control string is preceded by a screen position. Parameters (p1,...,pn) can be no more than 8 bytes.
The following routines are similar to printfat(), except you can specify an origin and relative offsets:
proff(xbase,ybase); set origin for prat() locations
int xbase,ybase;
prat(x,y,ctlstg,p1,...,pn);
printf() at a relative point on the screen
int x,y; screen coordinates (relative to the most recent proff() setting)
char *ctlstg; control string
p1,...,pn parameters (max 12 bytes)
The explode() family of routines (page 297) calls proff() to set the upper left corner of the exploded region. Then the choose() family (page 302) and edtval() (page 300) routines use prat() so that their coordinates are relative to the upper left corner of the exploded region.
cursact(movit); enable moving of blinking cursor
int movit; 1=move blinking cursor, 0=still
This routine selects whether the locate() routine will move the actual visible cursor or not. Whatever you pass to cursact(), locate() will still select the location written to by printf(), etc. But with cursact(0), the blinking cursor will remain stationary. cursact(1) is the default condition.
belper(pitch); beep the operator console
int pitch; 0=silent 200-1000 high-low pitch
This routine defines the handling of printf() when sending an ASCII bel (ctrl+G) character to the operator console. This will probably be a much shorter beep than DOS uses. For example:
belper(200);
printf("\7"); /* high-pitched beep */
belper(1000);
printf("\7"); /* low-pitched beep */
belper(150);
printf("\7"); /* very high-pitched beep */
belper(0);
printf("\7"); /* silent */The belper() routine is used in the Major BBS to set the beeps for signup notification (SGNBEL), the page-Sysop warning (SOPBEL), and the emulation screen (EMUBEL).
ansion(on); enable/disable ANSI graphics
1=process ANSI graphics sequences
0=ignore ANSI graphics sequences (display as literal)
This function turns on or off printf()'s interpretation of ANSI graphics characters embedded in the text stream. The following ANSI commands are supported when ansion(1) (the non-default condition) is in effect:
####### ANSI Commands
esc [<row>;<column>H Move cursor to <row>,<column>
esc [<row>;<column>f Move cursor to <row>,<column>
esc [<nrows>A Move cursor up <nrows> rows
esc [<nrows>B Move cursor down <nrows> rows
esc [<ncols>C Move cursor forward <ncols> columns
esc [<ncols>D Move cursor backward <ncols> columns
esc [s Save cursor position
esc [u Restore cursor position
esc [2J Erase display
esc [K Erase to the end of the current line
esc [0m Normal display attribute
esc [1m Bold display attribute
esc [4m Underscore display attribute
esc [5m Blink display attribute
esc [7m Reverse display attribute
esc [8m Invisible display attribute
esc [30m Black foreground
esc [31m Red foreground
esc [32m Green foreground
esc [33m Yellow foreground
esc [34m Blue foreground
esc [35m Magenta foreground
esc [36m Cyan foreground
esc [37m White foreground
esc [40m Black background
esc [41m Red background
esc [42m Green background
esc [43m Yellow background
esc [44m Blue background
esc [45m Magenta background
esc [46m Cyan background
esc [47m White background
None of the above commands include any spaces.
esc the Escape character, ASCII 27
<row> one or two ASCII digits representing the screen row, between 1 and 25. Defaults to 1 if omitted.
<column> one or two ASCII digits representing the screen column, between 1 and 80. Defaults to 1 if omitted. The ; may be omitted if the <column> parameter is omitted.
<nrows> one or two ASCII digits representing the number of screen rows, between 1 and 25. Defaults to 1 if omitted.
<ncols> one or two ASCII digits representing the number of screen columns, between 1 and 80. Defaults to 1 if omitted.
The m commands (display attributes) may be combined using semicolons. For example, esc [1m esc [33m esc [45m has the same effect as esc [1;33;45m Both commands set the display attribute to bright yellow on magenta. The following code displays a message with these attribute settings in the current display window:
printf("\33[1;33;45mWafer yield for the 200MHz P6: 85%");The individual characters of the above commands may be split across different calls to printf(). There may even be intervening calls to printf() as long as the intervening calls have ansion(0) (ANSI graphics disabled). Also, the display attribute is preserved across calls to setatr() when ansion(0). All of these features enable the emulation of a single user’s channel with ANSI graphics while the Major BBS simultaneously updates various other information on the console. For more on how the Major BBS emulates multiple screens at once, see page 273.
Note: the move cursor command is relative to the upper left corner defined in the most recent call to setwin() (not to the upper left corner of the screen buffer, as is the locate() function).
To convert IBM display attributes into ANSI sequences, use ibm2ans():
bufptr=ibm2ans(attr,buffer);
Convert IBM attribute to ANSI colors
char *bufptr; copy of buffer
char attr; attribute (see page 265)
char *buffer; where to put ANSI sequence (up to 15 bytes, including terminator)
The following code example shows some of these video routines in action. The zipred() function makes a red box with an exclamation point zip across the screen from left to right, and then disappear. Note that the image (of the original screen with a red box on it) is constructed in a buffer and then copied to the visible screen, so the red box does not flicker.
void
zipred(void)
{
static char savebf[4000]; /* buffer to save original screen image */
static char drawbf[4000]; /* buffer to use as a drawing board */
char *frzseg(); /* frzseg() returns a char pointer! */
int savx,savy; /* to save cursor position */
int x;
savx=curcurx(); /* save cursor position */
savy=curcury();
movmem(frzseg(),savebf,4000); /* save screen image */
setatr(0x4F); /* bright white on red */
for (x=0 ; x < 70 ; x++) { /* From left to right... */
movmem(savebf,drawbf,4000); /* prepare drawing board */
setwin(drawbf,x,9,x+10,15,0); /* define an 11 by 7 window */
printf("\f"); /* fill it with red */
locate(x+5,12); /* and in the center */
printf("!"); /* put an "!" */
rstwin(); /* (restore window settings) */
movmem(drawbf,frzseg(),4000); /* make this picture visible */
}
movmem(savebf,frzseg(),4000); /* restore original screen image */
locate(savx,savy); /* restore cursor position */
setatr(0x07); /* white on black */
unfrez();
}To read from the video screen or buffer, you can use scnoff():
offset=scnoff(x,y); Compute the offset
int offset;
int x,y;
For example, to find the character and attribute at the lower right corner of a SCNSIZ-byte screen buffer:
lrchar=scnbuf[scnoff(79,24)];
lrattr=scnbuf[scnoff(79,24)+1];To support ANSI capability on several screens at once, you must save some internal variables. The printf() routine only supports one screen and can keep track of partial ANSI commands. To support several screens, you must save the entire curatr structure. Note that curatr is the name for a structure type as well as the name of an instance of that structure type.
For example, you could maintain an array of curatr structures and make one of them active whenever you wrote to one of the screens.
struct curatr ansave[NUMSCNS];
:
movmem(&ansave[actscn],&curatr,sizeof(struct curatr));
printf(ANSI commands to screen);
movmem(&curatr,&ansave[actscn],sizeof(struct curatr));The first movmem() puts the curatr structure for the active screen where printf() will use it and update it. The second movmem() saves it away again.
Note: curatr.attrib is the attribute setting of the most recent setatr.
yes=kbhit(); Has the operator pressed a key?
int yes; 1=yes 0=no
After checking the standard library routine kbhit(), the Major BBS uses this routine to input a single keystroke.
char=getchc(); Get a keystroke from the keyboard
int char;
Note that getchc() returns a 16-bit value. GCOMM.H contains numerous constants for the return value of getchc(). The values are either extended ASCII in the lower 8 bits, or the keyboard scan code in the upper 8 bits.
Here are appropriate constants for representing the return values of getchc(). You can use these in the C-language cases of a switch statement:
' ' through '~' (printable ASCII characters 20 to 7E)
\x00 through \xFF (all ASCII plus extended characters)
F1 SHIFT+F1 CTRL+F1 ALT+F1
F2 SHIFT+F2 CTRL+F2 ALT+F2
F3 SHIFT+F3 CTRL+F3 ALT+F3
F4 SHIFT+F4 CTRL+F4 ALT+F4
F5 SHIFT+F5 CTRL+F5 ALT+F5
F6 SHIFT+F6 CTRL+F6 ALT+F6
F7 SHIFT+F7 CTRL+F7 ALT+F7
F8 SHIFT+F8 CTRL+F8 ALT+F8
F9 SHIFT+F9 CTRL+F9 ALT+F9
F10 SHIFT+F10 CTRL+F10 ALT+F10
HOME CTRLHOME BAKTAB
END CTRLEND INS
PGUP CTRLPGUP DEL
PGDN CTRLPGDN TAB
CRSRLF CTRLLF ESC
CRSRRT CTRLRT
CRSRUP CTRLUP
CRSRDN CTRLDN
ALT_A ALT_K ALT_U ALT_0
ALT_B ALT_L ALT_V ALT_1
ALT_C ALT_M ALT_W ALT_2
ALT_D ALT_N ALT_X ALT_3
ALT_E ALT_O ALT_Y ALT_4
ALT_F ALT_P ALT_Z ALT_5
ALT_G ALT_Q ALT_6
ALT_H ALT_R ALT_7
ALT_I ALT_S ALT_8
ALT_J ALT_T ALT_9
The codes that these constants represent are used in many contexts, online and offline. See AIN.H for converting incoming ANSI sequences into these keystroke codes.
To control the video screen cursor:
cursiz(howbig); Set the size of the video cursor
int howbig; NOCURS cursor disappears
LILCURS small standard cursor
BIGCURS big insert-mode cursor
rstcur(); Restore the cursor to the size it was before the last cursiz()
howbig=curcurs(); Find out how big the current cursor is.
int howbig; NOCURS, LILCURS, or BIGCURS