Date: Sat, 12 Mar 1994 9:40:20 -0500 (EST)
From: "Chris Mr. Tangerine Man Tate" <FIXER AT FAXCSL DOT DCRT DOT NIH DOT GOV>
To: djgpp AT sun DOT soe DOT clarkson DOT edu
Cc: FIXER AT FAXCSL DOT DCRT DOT NIH DOT GOV
Subject: SUMMARY - Text screen I/O

A number of people have requested a summary of responses to my question
about doing text-screen I/O under the go32/djgpp system.  Here's what
I've found.

First, none of this stuff is documented beyond the (sketchy) discussion
in libpc.doc and the (even sketchier) <pc.h> header file.  C'est la vie. :-(
As a result, I'm going to make this a fairly comprehensive summary of what
is going on, as far as I can tell, so that at least *somewhere* there'll
be a general explanation of how it all works.  For posterity, or something
like that.  :-)

Second, writing directly into the ScreenPrimary[] array *fails* under
DPMI, and reportedly under DeskView as well.  To work properly under a
DPMI environment, you either have to use SetScreenChar(), or you have to
malloc() and use your own virtual screen (more on this later).  Some
people suggested that this DPMI limitation might have been limited to
the original release of DJGPP 1.10; my experience is that it's still
a problem in 1.11.maint3 (the most recent I could find).

The screen array is an array of 'short's, stored in row order starting
with the top left corner.  So, on an 80-column screen, ScreenPrimary[0]
is the top left character, while ScreenPrimary[80] is the character
directly below that, etc.

Any array of shorts can be used as a 'virtual' screen, as long as its
dimensions are the same as the actual ScreenPrimary[] array.  To do this,
you write into your 'virtual screen' array as though it were the actual
screen, and call UpdateScreen(yourScreen) when you're done, to refresh
the physical screen to match your virtual one.

Attributes are the standard DOS ones - the low three bits are the foreground
color, bit 3 is the 'bright foreground' bit, the next three bits are the
background bit, and the high bit is the blinking/hilite bit.  Attributes
are stored in the high byte of a given screen location; the low byte
holds the actual character to display there.  So, as in the example in
the libpc.doc file, this:

          ScreenPrimary[0] = 'X' | 0x0600;

sets the top, left charcter to be an uppercase 'X', colored brown on a
black background.  Doing the same thing without writing into the screen
array is done by saying:

          SetScreenChar('X', 0, 0, 0x06);

(I might have the order of arguments wrong; I *think* its 'character, x-
coord, y-coord, attribute byte').

The problems I was having with getting characters to show up on the screen
were related to not maintaining coordinates correctly, not to any problems
with using SetScreenChar().  Oops.  :-)

IMHO it's unfortunate that you can't write directly to the ScreenPrimary[]
array under DMPI; that makes it impossible to use high-quality double-
buffering schemes to update only a region of the window at any one time.
For text graphics it's not so major an issue as it is for VGA/SVGA, but
it's still ... inelegant.  :-)  I do consider this a bug in go32, but
not a major one.  If it gets fixed in a later release, I'll be very
pleased, though.

-- Chris Tate
   fixer AT faxcsl DOT dcrt DOT nih DOT gov