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


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
implementation of VBE 2.0 for your video card, the example programs should
work (with the exception of the palette example, which fails for unknown
reasons).  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.

I have only tested this code with Watcom C++ v10.5.  Later versions
should work fine, but I make no guarantees.  Earlier versions may work,
but I doubt it.

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__.
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.  Since
 there is currently no support for banked video modes, it doesn't really
 do anything, except make you look like you know what you're doing.

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

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

"wait for retrace" - causes the library to wait for vertical retrace
 at every page update.  This prevents (well, reduces, just to be safe)
 tearing and can also be used to slow the frame rate down to the
 hardware refresh rate.

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.

Due to some of the compiler's weirdness, I have been forced to tell it
to ignore a certain warning in Surface.h.  Otherwise it complains about
a base class being inherited with private access, which is exactly
what is happening, I just don't see why it deserves a warning.

4.  Future versions

The main thing that's missing from this release is support for banked modes.
At the moment the way I'm thinking of doing this is to use a buffer in
system memory for the console, and copy the entire thing to video memory
on an update().  Area updates would also be possible.  Other suggestions are
welcome.

5.  Bug reports

If you have a bug report, email it to me with at least some kind of
description of the problem.

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.

(please, no questions about when I'm going to do jni/rni and create
a dynamic library :)

anyway, enjoy.

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