PTC 2.0 API, Watcom C++ DOS port
v 2.0.2 (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 examples should work.
For the Area and Tunnel examples, you only need a VGA compatible card.

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,
as well as the assembler fakemode conversion, which means another speed
increase for fakemodes.  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
routines in the libraries, add "asm=yes" to the wmake command line.

This code has been tested with Watcom C++ versions 10.5 and 11.
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_DOS__.  This has changed from
previous versions, since VGA support has been added.  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 might mean
 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.

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 and fakemode support is in, there isn't really too much
more to add.  The main thing left to add at the moment is DJGPP support.
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)
