PTC 2.0 API, DOS port.
v 2.0.6 (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.

There are two sets of makefiles, one for Watcom C++ ("makefile.wat"
in each directory), the other for DJGPP ("makefile.dj").  The included
batch file, setmake.bat, copies the relevant set to "makefile" in
each directory.  For Watcom C++, run "setmake watcom", and for DJGPP,
run "setmake djgpp".

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 libraries (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.

If you have Watcom C++ v11.0, or an earlier version with the library
utility (WLIB) from v11.0, you can use the assembler converters in
the Hermes library and the assembler fakemode conversion routines,
providing a significant speed boost when conversion is required.
To include the assembler routines, add "asm=yes" to the wmake
command line.

To compile everything with DJGPP, simply type "make" in the top level
directory 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, which is a bad move)

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.10 of the PTC Porting Kit, and as such any
bugs not due to the VBE and VGA interfacing code are entirely Gaffer's
fault :)

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 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. (or not running at all,
 if you use modes bigger than 320x200 :)
"no linear modes" - prevents the use of linear video modes.
"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.
 (it is disabled by default because it can cause problems)
"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.
"default width <width>" - specifies the default width of the console.
"default height <height>" - specifies the default height of the console.

These strings are all case independant.

The Console constructor now reads a configuration file, "ptc.cfg",
in the directory the program is run from.  This file can contain
any of these option strings, one to a line.  They are applied in
the order they appear in, so multiple fakemode, width, or height
options override each other.  No error messages or anything will
appear if any of the options are not accepted, so it is possible
to use comments (just begin the line with a '#' or something similar)
This means you don't have to write any user configuration code yourself,
and everyone knows that, given the choice, you wouldn't do it :)

Note that you can also read your own files with the read_config_file
API extension, described below.

Currently available API extensions:

 - bool Console::vrstate() - returns true if retrace checking is enabled

 - void Console::vrstate(bool state) - sets the retrace checking state

 - void Console::read_config_file(char *name) - reads a config file
   Note that this will not complain under any circumstances.  If the
   file does not exist, nothing happens.  If the file contains
   unrecognised option strings, they are ignored.


3.  Bugs, weird things, and miscellaneous notes

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.

In banked modes, video memory is not cleared at startup, since it
seems to crash sometimes.  I really don't know why.

The DOS version of nasm tends to run out of memory when used from a
makefile, so you either have to run it separately to compile the
assembler routines, use the windows version included in the distribution,
or compile a DOS 32-bit version yourself.

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.

Note to DJGPP users:  in the last release, (2.0.5) I forgot to save
the makefiles with tabs instead of spaces, and so they didn't work.
If this happens to you, load them in some reasonably intelligent
text editor (QEdit etc.) and fix them.	(qedit makefile.dj, esc-o-m,
esc-f-s, esc-q-q :)

Also note that although the executables DJGPP produces are very large,
(around 400k) most of this is just debug information.  If you compress
them with something like UPX, (http://cdata.tvnet.hu/~ml/upx.html)
they actually come out smaller than the compressed Watcom executables.
(because Watcom uses a larger stub)

Watcom's default stack size is much too small for PTC to be able to
do anything without overflowing it.  If you look at the makefiles for
the example programs, they are given 256k of stack.  When linking
your own code with PTC, it is very important to remember to do this.
If you forget, and you compile your code without stack checking,
this will lead to strange crashes that you probably won't be able to
trace properly.

PTC is not suitable for 64k intros.  It probably wouldn't be too hard
to take the VBE class, turn it into C, and take some of the converter
routines from Hermes, and make yourself a small VBE interface, but
I'm not going to do it for you..

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

Of course, if you think of a feature that I seem to have missed,
then tell me about it..

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)
