PTC 2.0 API, DOS port.
v 2.0.5 (alpha) by zoon/food.

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++, or DJGPP v2, it should compile.  As long as you have a VGA
video card (or better :) the examples should work.

I have included what seems to me to be a reasonable set of makefiles for
each compiler.  The Watcom makefiles are called "makefile.wat", the
DJGPP makefiles are called "makefile.dj".  To actually use any of the
makefiles, rename the files for the compiler you're using to just
"makefile" in each directory.

To compile everything with Watcom, simply type "wmake" in the top level
directory, and wait a while.  This compiles both debug and release versions
of the librareis (PTC and Hermes), as well as all the examples.  To compile
just the PTC library, type "wmake" (or "wmake config=debug" for the debug
version) in the source directory.  To compile Hermes, type "wmake" in the
source\hermes directory.  To compile a specific example, type "wmake
<name of example>" in the examples directory.

To compile everything with DJGPP, simply type "make" in the top level
and wait a while.  Everything else is the same as compiling with Watcom,
except that to compile specific examples, it is necessary to add the
".exe" suffix to the example name.  (this is because GNU make thinks
it knows how to make files with no extension.. it tries to link the
example object file, without any of the libraries)

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.

Due to some strangeness in DJGPP's code generator, (I think) the
C++ fakemode conversion routines do not work.  I couldn't be bothered
figuring out why when it was quicker and easier to just force the usage
of the assembler routines, which do work.  DJGPP users must install nasm
to be able to compile PTC.  Don't complain, it's faster this way :)

This code has been tested with Watcom C++ versions 10.5 and 11, and
DJGPP v2 (only the regular distribution, not PGCC or EGCS or anything
like that.. if you try it with these, tell me how it goes)
It probably won't work with Watcom C++ v10.0.  It will definitely not work
with DJGPP v1.x.  If you're still using it, upgrade.  Really.

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 vbe modes" - prevents the use of VBE modes.  Use this to see what
 your program looks like running in a fakemode.
"no banked modes" - prevents the use of banked video modes.
"no vga modes" - prevents the use of VGA modes.
"no retrace checking" - disables retrace checking on console updates.
"force exact match" - only allows video modes that exactly match your
 specified resolution.
"force offscreen buffering" - ensures that the console is in system
 memory, and updates copy from system to video memory.
"disable wide dac" - disables use of 8-bit DAC in indexed modes.
"enable pmode interface" - enables the VBE 2 protected mode interface.
"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.

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.

There are many strange things that happen when using DJGPP.  The startup
code (or something) seems to crash occasionally, the iostream libs don't
appear to work, the old tunnel example crashes before any PTC code is
called.. and makefiles behave quite strangely too.  If you can sort
any of this out for me, (at present I have been working with DJGPP for
a grand total of two days) without destroying the Watcom support, send
it to me.

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

At the moment, pretty much everything I wanted to have in this port has
been done.  If you're thinking this means I'm going to start working on
area updates for fakemodes, forget it :)

All that's left is fixing my stupid mistakes, updating the classes to match
with the final PTC 2.0 API when it's finished, and upgrading to later
versions of Hermes when they arrive.. unless someone can find a reasonably
widely used 32-bit C++ compiler for DOS that they want support for.
(that does NOT mean Borland C++ :)

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)
