PTC 2.0 API, Watcom C++ DOS port
v 2.0.4 (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.

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.9 of the PTC Porting Kit, and as such any
bugs not due to the VBE and VGA 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.

"no vga modes" - this prevents the use of VGA modes.  VGA modes have
 much worse visual quality than VBE modes, due to limited colour depth,
 (8 bits in mode 13h, 14 bits in the current fakemode) and tearing due
 to limited video memory.

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

"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.

"force offscreen buffering" - ensures that the console is in system
 memory, and updates copy from system to video memory.  This is useful
 when you expect to only be updating small sections of the console,
 and flickering is not a problem.

"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 :)

"disable pmode interface" - disables use of the VBE 2 protected mode
 interface.  It is known to cause some problems, so it might be a good
 idea to allow the user of your program to disable it.

"fakemode XX" - sets the fakemode to be used.  XX is one of 1A, 1B, 1C,
 2A, 2B, 2C, 3A, 3B, or 3C.  Try them to find out which suits you best.
 (remove VBE20 TSRs, and use the "no banked modes" console option)

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.

Sometimes the screen doesn't seem to be cleared when changing modes.
In linear modes, all available video memory is cleared, but in banked
mode it crashes when I try to do it.  The code is commented out in
VBE::vid_set_mode().  If you have the time, and don't mind the odd
GPF, it'd be nice if I could get that sorted out.

4.  Thanks

Extremely large thanks must go to Mikko Tiihonen (Mikko.Tiihonen@hut.fi)
for doing lots of testing, adding support for wide DACs and the VBE 2
protected mode interface, 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.

6.  Bug reports

If you have a bug report, first make sure you have the latest version,
then 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 :)

anyway, enjoy.

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