PTC 2.0 API, Watcom C++ DOS port
v 2.0.1 (alpha) by zoon/food, 15/10/98.

This package and all included source code is licensed under the GNU
LGPL.  Please refer to the included file COPYING.LIB for the exact
terms.

For a history of changes, refer to changes.txt.

1.  Installation/testing instructions

As long as the archive was extracted with subdirectories, everything
should be in place, and as long as you have at least version 10.5 of
Watcom C++, it should compile.  As long as you have a working VBE
implementation for your video card, the example programs should
work.  Hopefully that's not too much to ask.

I have included what seems to me to be a reasonable set of makefiles.
To compile everything (release and debug libraries and example programs)
just type "wmake all" in the directory you unzipped everything.
In the example directory, you can type "wmake <name of example>" to
compile individual examples.  To compile them with debugging information,
add "config=debug" to the command line.  In the source directory, you
can compile the release version of the library just by running wmake.
To compile the debug version, type "wmake config=debug".

If you have the library utility from Watcom C++ v11, you will be able
to use the assembler pixel converters in the Hermes library, which
means a significant speed increase when pixel conversion is necessary.
You will also need at least version 0.96 of nasm, which can be found at
http://www.cryogen.com/Nasm.  To include the assembler converters in
the library, add "asm=yes" to the wmake command line.

This code has been tested with Watcom C++ versions 10.5 and 11.
(the weird doesn't-work-with-watcom-11 bug has been fixed, I
wasn't using the right #pragmas to pack the structures..)
It may work with earlier versions, but no guarantees.
If you can get it working, send me patches to the code.

2.  Implementation details

This port was based on v2.0.7 of the PTC Porting Kit, and as such any
bugs not due to the VBE interfacing code are entirely Gaffer's fault :)
The interface to the Hermes pixel conversion library was taken from
the PTC X11 port.

Things I am required by law (sort of) to tell you:

The platform #define (in ptc.h) is __PTC_VBE__.  When fakemode support
is added, it will be changed to __PTC_DOS__.  The only API extensions
currently available are used to determine whether or not to wait for
vertical retrace at every page update.  Console::vrstate() returns true
if waiting is enabled.  Console::vrstate(bool newstate) is used to set
the state.

The available option strings are:

"no banked modes" - this prevents the use of banked video modes.  Banked
 are slower than linear modes, but most people don't have VBE 2.0
 compatible video cards.

"force triple buffering" - this causes the library to throw an exception
 if not enough video memory is available for triple buffering.

"force exact match" - only allows video modes that exactly match your
 specified resolution.  This isn't terribly useful, since it means less
 people will be able to watch whatever you're coding.

"no retrace checking" - disables retrace checking on console updates.
 This allows frame rates faster than the hardware refresh rate, but
 can cause tearing.

"disable wide dac" - disables use of the 8-bit DAC capabilities of
 some cards when in indexed screen modes.  Only use this if you have
 something against people seeing things in better quality than you :)

3.  Bugs and just plain weird things

As with any code that has anything to do with VBE, there's probably
a maze of little twisty bugs, all alike in here.  If this code refuses
to work properly with your video card, tell me about and I'll see what
I can do to fix it.  However, this code is based on some of my old VBE
code, which was itself based on the code from PTC 0.x, so it should
work reasonably well.

While testing banked mode support with my video card, (S3 Virge based)
I found that the card's VBE implementation refused to perform page
flips when the wait for retrace flag was set.  I have included a basic
check for this, which turns off retrace checking.

4.  Thanks

Extremely large thanks must go to Mikko Tiihonen (Mikko.Tiihonen@hut.fi)
for doing lots of testing and spotting a lot of my stupid mistakes :)
and also to Geir Bjerke, Jeroen Janssen, and Dan Brown for helping out too.
Every stupid bug spotted brings me one step closer to having this thing
completely finished :)

5.  Future versions

Since banked mode support is in, there isn't really too much more to add.
I intend to add fakemodes (similar to PTC 0.x) and possibly DJGPP support,
as well as improving the banked mode console update, which is less
efficient than it could be.  If you have the overwhelming urge to help,
(don't let me stop you :) have a look at the TODO file, maybe you'll find
something in there.

6.  Bug reports

If you have a bug report, first check coders.ptc.bugs on news.scene.org
to see if anyone else has reported it, and if not, email it to me with at
least some kind of description of the problem. (and post to coders.ptc.bugs
too :)

In future versions I might include code to generate some kind of log of
everything that happens, which might make it easier to figure out where
I screwed up.

anyway, enjoy.

zoon/food. (jmatthew@uq.net.au)
