Power-Programmierung/CD1.mdf/assemblr/library/ansi/nnansi/nnansi.doc

Text File | 1990-10-12 | 27KB | 719 lines

        NNANSI.SYS -- Enhanced MS-DOS ANSI Console Driver
                      For EGA/VGA Displays

Documentation for version 8/90.

Note: MS-DOS is a trademark of Microsoft Corporation, and PC/XT,
PC/AT, and PS/2 are trademarks of IBM Corporation.


*********INTRODUCTION

NNANSI.SYS (version 8/90) is an improved version of NANSI.SYS
(version 2.2), by Daniel Kegel, which is in turn such an
improvement over ANSI.SYS that *no one* should be without one of
these.

If you are using ANSI.SYS, be aware that either of these drivers
will offer greatly improved performance and functionality over
your current driver. Current users of NANSI.SYS with EGA or VGA
displays (and other enhanced ANSI.SYS drivers) will notice still
greater performance and functionality in NNANSI.SYS.

Even if you don't use an ANSI.SYS driver, you will the
performance benefits. (Note that there will be no performance
benefits for programs that write directly to the display).


A short list of improvements of NANSI.SYS (version 3.0) over
ANSI.SYS:

1. Intrinsic 43 or 50 line support.

2. Some additional text mode escape sequences: Insert Lines,
        Delete Lines, Insert Characters, Delete Characters.

3. Greater to *much* greater performance.

4. Supports higher resolutions, both text and graphic modes.

5. Graphic mode cursor


A short list of improvements of NNANSI.SYS (version 8/90) over
NANSI.SYS:

1. Additional escape sequences: erase to start/end of display,
        insert/delete lines in graphic modes, added Set Graphic
        Rendition codes (and working reverse video).

2. Graphic cursor support is better, and can be disabled.

3. Intrinsic support for both 43 and 50 line modes on a VGA.

4. Faster text mode performance; *much* faster scrolling
        (when in "fast mode").

5. Much faster performance in 640x350 (or greater) 16 color
        graphic modes. Every ANSI control sequence (except
        insert/delete characters and blink) work in these modes
        as well.

6. Readily configured for enhanced graphic and text modes of
        various display cards. Support for several popular cards
        are provided.

7. Blink in 16 color graphics modes will exclusive-OR characters.


On the other hand, NANSI works with CGA, MDA, or Hercules
displays, and is smaller.


**********************LICENSE REQUIREMENTS

Daniel Kegel is the author of NANSI.SYS, of which this is a
derived work. I, Tom Almy, think enough of his efforts and
programming skills that I used NANSI.SYS as a base for
NNANSI.SYS (version 2.2 came with sources and free distribution
for personal or educational use, but prohibits commercial use).
I have an agreement with Mr.  Kegel to license NNANSI.SYS in
accordance with his newest NANSI.SYS license arrangement:

"If you use this program for education or at home, you are
encouraged to send a US$10 donation to the author.  If you use
it for business purposes, you are required to purchase a
right-to-use license by sending US$10 to the author."

Send contributions/user fees to:

        Daniel Kegel
        221 Fairview Ave.
        South Pasadena, CA  91030

You can also reach him at his internet address:

[e-mail]


Everyone wins with this arrangement!

* Commercial users can now legally use NNANSI.SYS

* Personal users can show their gratitude.

* Daniel Kegel can make a little money for his efforts.

* I won't feel guilty for "ripping off" his work.


I place no restrictions on my modifications to NANSI.SYS. I
neither request nor will I accept any contributions for my work
on this program. I made these modifications as part of an effort
to understand the workings of DOS device drivers and the EGA/VGA
display.

On the other hand, I do like to hear from users, satisfied or
(even) not satisfied. Please, if you have problems, check the
PROBLEMS section of this document before contacting me.

My address is:

        [e-mail]        (Internet)

or

        Tom Almy
        17830 SW Shasta Trail
        Tualatin, OR 97062

if you must use the postal service. Enclose a stamped, self-
addressed envelope if you desire a reply.



*********DISTRIBUTED FILES

The distribution has the following files:

        nnansi.sys      - Driver, with compilation options set as shown
                        - in the source file nnansi_d.asm
        gcon.bat        - turns graphic cursor on
        gcoff.bat       - turns graphic cursor off
        fast.bat        - turns fast mode on
        slow.bat        - turns fast mode off
    25.bat        - set 80x25 text mode
    43.bat        - set 80x43 text mode
    50.bat        - set 80x50 text mode (VGA only)
        nnansi.doc      - this file
        makefile        - for Don Kneller's NDMAKE
        nnansi_d.asm    - definitions **** READ THIS ****
        nnansi.asm      - device driver guts
        nnansi_p.asm    - ANSI parameter grabber
        nnansi_f.asm    - ANSI function handlers
        nnansi_i.asm    - device driver init routine (must link last)


*********INSTALLATION

NNANSI.SYS installs just like ANSI.SYS (or NANSI.SYS), it is a
device driver that you specify in your CONFIG.SYS file:

        DEVICE=NNANSI.SYS

If you are using code pages, place this command before the
DEVICE=DISPLAY.SYS command, otherwise code pages will not work.

While the supplied compiled driver is suitable for most
installations, you can get better results by customizing the
driver for your display card. To do this you will need an
assembler, such as Borland Turbo Assembler, a text editor, and
(optionally) Don Kneller's NDMAKE program.

All options are specified in the file NNANSI_D.ASM. Edit that
file and make changes as appropriate. These descriptions assume
the initial default settings:

VGA     (TRUE)
        If you have an EGA display, set this to FALSE. You might
        also want to set this to FALSE if you have a VGA and are
        used to the ESC [=43h sequence supplying 50 line mode.

EGA     (TRUE)
        If you have a VGA, set this to FALSE.

VEGA, PARADISE, STBVGA...  (all FALSE)
        Set only one of these TRUE to match your enhanced
        EGA/VGA display card. If you have a card not on the list
        and experience problems with either blotches in enhanced
        text mode or poor performance (unsettable background
        colors is a clue) in graphics modes CONTACT THE AUTHOR.

cheap_pc (TRUE)
        Set to FALSE for "PC/AT" and "PS/2" class machines which
    have 80186 or greater processors.

key_redef (FALSE)
        Set to TRUE if you use key redefinition. There are
        Trojan Horse programs that take advantage of this
        feature, and most people don't use it anyway, so the
        default is FALSE.

init_buffer_size (256)
        Enlarge if you use key redefinition and don't have
        enough room.

quick_char (TRUE)
        Faster graphics display in 16 color modes, at cost of
    much extra code since this involves added display
    routines. Must be TRUE if non-BLACK graphic background
    colors are desired.

fast29  (TRUE)
        Makes int29 display calls (used by DOS) 15% faster at a
        cost of 100 bytes.

bios_write_tty (TRUE)
        The write tty BIOS call is taken over. It will now
        perform faster and understand ANSI escape sequences.
        This could confuse some programs. In that case, set this
        option to FALSE.

gbackground (TRUE)
        Enables setting of non-black background color in 16
        color graphic modes (except 640x200). If set to TRUE,
    quick_char must also be set to TRUE. If this feature is
    not desired, it is possible (depending on the system) to
    get greater performance by defining both gbackground and
    quick_char FALSE. This will also save quite a bit of
    code. Experiment and see for yourself.

initgc  (TRUE)
        Graphic mode cursor is initially on. Not a big deal
        since you can turn it on/off with a control sequence.

initfast (TRUE)
        Fast scroll mode is initially on. This also means that
        multiple page support is initially off. Not a big deal
        since you can turn it on/off with a control sequence,
        and there are other work-arounds as well.

You can then either use the supplied makefile to generate a new
nnansi.sys or assemble manually as shown (Borland tools
illustrated):

tasm /m5 nnansi                 (Use /m5 for version 2.0 or later)
tasm /m5 nnansi_f
tasm /m5 nnansi_p
tasm /m5 nnansi_i
tlink nnansi+nnansi_f+nnansi_p+nnansi_i,nnansi.sys/m/t

With the Microsoft assembler, you will need to use the exe2bin
program to convert the linker generated exe file into a binary
image file, which you then have to rename to NNANSI.SYS.


**************HOW MUCH PERFORMANCE IMPROVEMENT IS THERE?

I have performed considerable testing on a 25Mhz 80386 machine
with a Video 7 (Headland) Fastwrite VGA display controller (and
its BIOS), under both DOS 3.3 and 4.0. Your results will
probably vary, and BIOS performance without NNANSI.SYS will also
improve if the EGA/VGA BIOS is copied to RAM as supported by
some vendors and also posible with QEMM or 386/MAX on 80386 based
systems.

When using ANSI.SYS rather than no driver at all, there is
roughly a 2.3x degradation in performance if no scrolling
occurs. Scrolling performance improves 44% when DOS 4.0 ANSI
driver is used, but remains unchanged with the DOS 3.3 driver.

Compared to no driver, NANSI.SYS (3.0) is 3x to 3.5x faster when
no scrolling occurs, and is roughly 45x faster when going
through DOS in RAW mode. It is roughly 2x faster scrolling.

Compared to the no driver or other ANSI drivers, NNANSI.SYS is
4x faster in BIOS TTY write calls. Compared to NANSI.SYS it is
2x faster in INT29 calls, 73% faster in DOS calls, but there is
no speedup in RAW mode. When fast mode is used, scrolling is 15x
to 25x faster.

This means that text mode programs that take advantage of RAW
mode and buffering can display 100 times faster with NNANSI (and
without scrolling, NANSI) over ANSI.SYS. It works out to about
420,000 characters per second with my fast machine.

NNANSI.SYS also has speedups for 16 color graphic modes. With
the graphic cursor turned on, the TTY BIOS call is about 10%
slower than the standard BIOS call (which doesn't display a
cursor), but other output calls are 2.5x to 3.5x faster than
that of NANSI.SYS. Turning the graphics cursor off roughly
doubles the writing speed of all modes but RAW.



**************FAST MODE

To get maximum speed, NNANSI has what I call Fast Mode. In text
mode, there is more display memory than there are character on
the display. Normally, the BIOS supports display "pages" that you
can switch among. Changing the display page changes the region
of the display memory that is sent to the display. Fast Mode
uses the same technique (changing the starting location of the
viewable memory region) to scroll the display upwards.

Programs that make use of multiple display pages and scroll the
display require that fast mode be turned off. Many debugging
programs do this, to maintain separate debugging and application
displays. Some of the programs will still work in fast mode if
they have a "swap screens" option ("-ds" for Turbo Debugger, for
instance).

A number of programs that directly access the display don't work
if starting address has changed. These programs may not work
properly in fast mode (or in display pages other than the
first). NNANSI.SYS tries its best to work with these programs by
resetting the display start location if any program does the get
display mode or scroll/clear display BIOS calls. These calls are
typically done by offending applications when they start. As
long as the display never scrolls under NNANSI.SYS control
everything will work fine. A typical problem occurs in
potentially offending programs that have DOS or "shell escape"
commands. If the DOS sub-shell (invocation of COMMAND.COM)
causes the display to scroll, then upon exiting the sub-shell
the display will be ruined. The solution to this problem (other
than leaving fast mode) is to clear the screen just before
exiting the sub-shell.

Some offending programs can be "fixed" by invoking them from a
batch file (or alias if you use MKS Toolkit, 4DOS, ANARKEY...)
which first clears the screen. Or you can use a batch file which
turns off fast mode, then turn fast mode back on again after
program execution. Example:

echo ^[[=98l
offendingpgm %1 %2 %3 %4 %5
echo ^[[=98h

Where "^[" is the escape (code 27) character.

Batch programs have been provided to enable and disable fast mode.


******************WRITING PROGRAMS FOR BEST PERFORMANCE


To get best performance in programs you write, you must put the
display in RAW mode, and buffer output.

In assembler, you can set raw mode with the following sequence
(adapt this for other languages):

        mov     ax,4400h        ; get device status
        mov     bx, 1           ; of device 1 (standard output)
        int     21h
        xor     dh, dh          ; clear upper byte
        mov     saved_state, dx ; save it for later
        mov     ax, 4401h       ; set new status
        or      dl, 20h         ; with raw bit set
        int     21h

Reset raw mode before terminating the application:

        mov     ax, 4401h       ; set status to original values
        mov     bx, 1
        mov     dx, saved_state
        int     21h

There is a fixed amount of overhead (and it is high) for each
DOS call. Therefore you should buffer up write requests into a
single call. With the C language, you can use the setvbuf() call
to set a large buffer size.

Even if you don't follow this advice, you will get a major
performance improvement over ANSI.SYS (or no device driver at
all).

Programs using RAW mode and buffering easily beat the
performance of the supposedly high speed console drivers
supplied in Turbo C and Microsoft C. And by using ANSI control
sequences your programs can be made portable to other systems!


*****************TYPICAL PROBLEMS

SYSTEM CRASHES UPON BOOTING, OR DISPLAY BADLY CORRUPTED EVEN IN
STANDARD 80x25 TEXT MODE.

You have compiled NNANSI.SYS with cheap_pc set to FALSE on an
8088 based system, or you are trying to use NNANSI.SYS on a CGA,
MDA, or Hercules Graphics equipped system (it will never work in
this case).


ON A VGA, SETTING 43 LINE MODE GIVES 43 LINES, WHEN IT GAVE 50
WITH AN OLDER VERSION OF NNANSI.SYS OR WITH NANSI.SYS

This is correct. There is now a new setting for 50 line mode. If
you require that 43 line mode give 50 lines, recompile the
system with VGA set to FALSE.


ON A VGA, SETTING 50 LINE MODE CAUSES VERY STRANGE BEHAVIOR

Two possibilities. Your display adapter is really an EGA, or you
have compiled NNANSI.SYS with VGA set to FALSE. In the latter
case, you can get 50 line mode by setting 43 line mode, while in
the former case you can't get 50 line mode at all.


ON A VGA, AFTER LEAVING 43/50 LINE MODE THE CURSOR IS IN THE
MIDDLE OF THE CHARACTER BLOCK

Recompile the driver with EGA set to FALSE.


ON AN EGA, THE CURSOR DISAPPEARS IN 43 LINE MODE WHEN RUNNING
SOME APPLICATIONS

There is nothing you can do, as this is caused by an error in
the design of the EGA BIOS.


IN 43/50 LINE MODE, THE DOS CLS COMMAND ONLY CLEARS THE FIRST 25
LINES OF THE DISPLAY

I bet you are running DOS 4.0! The COMMAND.COM program in this
version does not recognize NNANSI.SYS and clears the screen
itself. Unfortunately it assumes that you are in 25 line mode.
There are four fixes: 1) Patch COMMAND.COM (good luck), 2) write
a batch file program which echoes the ANSI clearscreen sequence
to the display, 3) Switch to DOS 3.3, 4) Get a COMMAND.COM
replacement. I recommend the (share-ware) 4DOS from JP Software.


DISPLAY SHOWS UGLY BLOCKS AT THE START AND END OF EACH LINE IN
EXTENDED (GREATER THAN 80X25) TEXT MODES

Your display controller sets the display mode byte in the BIOS
to some value other than "3". You can either set the byte (at
location 40:49h) back to 3 after setting the display mode, or
configure NNANSI.SYS to know about these special modes. This
problem is typical for Paradise cards, and their clones. There
may already be a proper configuration for your display in
NNANSI_D.ASM.


DISPLAY IS NOTICEABLY SLOWER WRITING OR CANNOT SWITCH BACKGROUND
COLORS IN EXTENDED (GREATER THAN 640x480, OR 640x350 EGA)
GRAPHIC MODES

You will need to configure NNANSI.SYS for your display card.
Look for a proper configuration in NNANSI_D.ASM.


DISPLAY GOES BLANK WHEN STARTING AN APPLICATION. DISPLAY SHIFTED
PARTLY OFF SCREEN WHEN STARTING AN APPLICATION. DISPLAY
DISAPPEARS DURING EXECUTION OF A APPLICATION.

First try clearing the screen before execution. If that doesn't
work, leave fast mode (see preceding section on FAST MODE).


FUNNY BLOTCHES OCCASIONALLY APPEAR AT VARIOUS POINTS IN A
GRAPHIC APPLICATION

This is the graphics cursor. You can disable it either by
reconfiguring the driver, or by sending the control sequence to
disable the graphics cursor. A batch file has been provided for
this purpose.


TEXT DISPLAY IS MESSED UP, POSSIBLY CHANGING COLORS IN UNUSUAL
PLACES.

This has been observed with programs using the BIOS for writing
to the display, and not expecting the ANSI translation (or the
conversion of the TAB character into spaces instead of a special
graphic). The solution is to compile NNANSI.SYS with
bios_write_tty set to FALSE.


*****************NNANSI COMMAND SEQUENCES

Command sequences start with the escape character (code 27,
referred to in this section as ESC). NNANSI buffers up the
sequence until it has a command to execute. If the sequence is
not a valid command, the entire sequence is passed to the display.

All command sequences have the following format:

   ESC [ param1; param2; ...; paramN cmdchar

where
       ESC     is the escape character
       [       is the left bracket character.
       param   are ascii decimal numbers or quoted strings.
       cmdchar is the command character

No spaces are allowed within the command.

Omitted parameters default to "1", with the exception of the ED
(erase in display) command. For example, both ESC[1;1H and ESC[H
send the cursor to the home position (1,1), which is the upper
left.

Quoted strings may use either single or double quote characters
as delimiters. Each character inside the quoted string is
converted to a numeric parameter. Quoted strings are only useful
for the questionable Keyboard Key Reassignment command.



                   CURSOR POSITIONING COMMANDS

NAME    DESCRIPTION             COMMAND
CUP     cursor position         ESC[y;xH
HVP     cursor position         ESC[y;xf

        Either of these set the cursor position. CUP should be
        used since HVP has other connotations not implemented in
        NNANSI.SYS (or ANSI.SYS). The origin (in the upper left
        corner) is x=1, y=1.

CUU     cursor up               ESC[nA
CUD     cursor down             ESC[nB
        n = # of lines to move. You cannot move beyond the edge
        of the display.

CUF     cursor forward          ESC[nC
CUB     cursor backward         ESC[nD
        n = # of columns to move. You cannot move beyond the
        edge of the display.

DSR     Device Status Report    ESC[6n
        Find out cursor position. The driver responds with a
        cursor position report (CPR) of the form "ESC[y;xR"
        followed by a carriage return, as if typed at the
        keyboard.

SCP     Save Cursor Position    ESC[s
RCP     Restore Cursor Position ESC[u
        Cannot be nested.




                        EDITING COMMANDS

NAME    DESCRIPTION             COMMAND
ED      Erase in Display        ESC[nJ
        n=0 or missing: Erase to end of screen (not in ANSI.SYS)
        n=1: erase to start of screen (not in ANSI.SYS)
        n=2: erase entire screen, and home cursor
        Note: there is a bug in ANSI.SYS that performs function
        2 regardless of the value of n. This bug is not repeated
        in NNANSI.SYS because of the extra functionality provided.

EL      Erase in Line           ESC[K
        Erases from cursor to end of line

IL      Insert Lines            ESC[nL
        Inserts n blank lines at the line containing the cursor.
        While the cursor line moves down, the cursor position is
        unchanged. Not in ANSI.SYS.

DL      Delete Lines            ESC[nM
        Deletes n lines, starting at the line containing the
        cursor. The cursor is not moved. Not in ANSI.SYS

ICH     Insert Characters       ESC[n@
        Inserts n blank characters at cursor position. The
        cursor does not move. Not in ANSI.SYS. Does not work in
        graphic modes.

DCH     Delete Characters       ESC[nP
        Deletes n characters at the cursor. The cursor does not
        move. Not in ANSI.SYS. Does not work in graphic modes.




                  SET GRAPHIC RENDITION COMMAND

NAME    DESCRIPTION             COMMAND
SGR     Set Graphics Rendition  ESC[n;n;...nm

The Set Graphics Rendition command is used to select foreground
and background colors or attributes.  When you use multiple
parameters, they are executed in sequence, and the effects are
cumulative.  You can set all colors and attributes in any text
mode.  In 16 color graphic modes with at least 350 vertical
pixels you can set all colors and attributes except for blink.
"Blink" becomes exclusive-OR character mode (very useful!).  You
can set foreground colors, blink, and bold, only, in other 16 color
modes.  Setting colors does not work correctly for other color
modes -- make sure display is in the normal white on black mode
before changing to these modes.

Code          Value
0               All attributes off (normal white on black)
1               Bold
2               Dim (not Bold)
4               Underscore (emulated via blue foreground)
5               Blink (or EXOR -- see above)
7               Reverse Video (improved implementation over ANSI)
8               Invisible (improved operation)
22              Cancel Bold
24              Cancel Underline (white foreground)
25              Cancel Blink
27              Normal, un-reversed video
30-37           foreground black/red/green/yellow/blue/magenta/cyan/white
40-47           background black/red/green/yellow/blue/magenta/cyan/white

Codes 2, 22, 24, 25, and 27 are not in ANSI.SYS.



                    SET DISPLAY MODE COMMAND

NAME    DESCRIPTION             COMMAND
SM      Set Mode                ESC[=nh

The implementation allows using the RM command to do these
actions, and the "=" character is optional. But cheating in this
way is not a good idea.

The BIOS supports many video modes. The code given for the AL
register to the BIOS set mode command is used as the parameter
to this set mode command. That means that extended modes that
are settable in this manner can use this command. Display cards
that use other techniques to change display mode are left as an
exercise to the user, but if you can get the card into an
extended mode, NNANSI can used it (possibly with a configuration
change, though).

In the graphic modes, the cursor can be simulated with a blob
(the character produced with character code 22).

Mode Code       Value
    0,1         text 40x25 16 color
    2,3         text 80x25 16 color
    4,5         graphics 320x200 4 color
    6           graphics 640x200 Black & White
    7           [see next section]
    13          graphics 320x200 16 color, VGA only
    14          graphics 640x200 16 color, VGA only
    16          graphics 640x350 16 color, VGA only
    17          graphics 640x480 Black & White, VGA only
    18          graphics 640x480 16 color, VGA only
    19          graphics 300x200 256 color, VGA only
    43          43 line mode for mode 2 or 3 (Not in ANSI.SYS)
    50          50 line mode for mode 2 or 3 (VGA only, not in
                ANSI.SYS)
    98          [see next section]
    99          [see next section]
    n           When not in above list, sets mode n. (Not in
                ANSI.SYS)


The modes marked as VGA only are not supported by ANSI.SYS
that comes with version 3.3 MS-DOS or earlier.

The 43 line and 50 line support reprograms the display to use
smaller characters. Set mode 3 first, before using these modes.
Set any other mode to leave 43/50 line mode.

Unlike earlier versions of NNANSI.SYS, and NANSI.SYS, setting 43
line mode on a VGA will give 43 (not 50) lines. You must use the
explicit 50 line mode command to get 50 lines on a VGA. If you
would rather have compatibility with these other drivers,
recompile the driver with VGA set to FALSE.



                     SET DISPLAY ATTRIBUTES

NAME    DESCRIPTION             COMMAND
SM      Set Mode                ESC[?nh
RM      Reset Mode              ESC[?nl

Valid attributes that can be set and reset:

7       Cursor Wrap     When false, cursor sticks at end of
                        line, rather than wrapping

98      Fast Scroll     When true (fast mode) the starting
                        display location is changed for fast
                        scrolling, which can cause problems for
                        some programs. When false, the starting
                        location does not change and the
                        multi-page support is enabled.

99      Graphic cursor  When true the cursor is displayed in
                        graphic modes.

Batch files are supplied to change attributes 98 and 99.



                  KEYBOARD REASSIGNMENT COMMAND

This command is absent by default. You must recompile to enable
this command.

NAME    DESCRIPTION             COMMAND
IBMKKR  Keyboard Key Reassign   ESC[param;param;...;param p

If no parameters are given, all keys are reset. This is not true
for ANSI.SYS.

The first parameter is the key to reassign. IBM function keys
take the first two parameters, where the first parameter is 0.
The remaining parameters are the keystrokes to substitute. F11
and F12 are not supported. Normally a string is used rather than
numeric arguments.


******************************THE END****************************