PTC 2.0 API, DOS port.
v 2.0.7 beta by Elemental / Cranium


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

First off all, sorry for this very unfinish version of ptc dos. I am
"forced" to release it now because I will lose my internet account
very soon. Therefore I won't be able to release a final version. But
I hope this will inspire somebody to add the 2 missing functions
console::flush and console::finish and the incomplete function
console::read (and console::key).

This version has been a crude hack from ptc dos 2.0.6 by zoon/food,
which I updated for with the PTC porting kit and the Hermes porting
kit. (hell, even this readme.txt is a hack off his)


2.  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 VGA video card
(or better :) the examples should work.

Unfortunately i have only watcom v11.0 installed, but there shouldn't
be any problems with watcom v10.5. DJGPP support lacks.

First of all you have to download hermes 1.2.2 (Christian said 1.2.3
will be compatible with 1.2.2, so if it is release, use it ;)) and
unpack it, read the manual, compile it and copy the hermes library
in de library directory of ptc dos in either the debug or the release
subdirectory.

To compile everything with Watcom, simply type "wmake" in the source
directory, and wait a while.  This compiles both debug and release
versions of the library (PTC). For the debug version type "wmake
config=debug" in the source directory. To compile the examples type
"wmake" in the examples directory. To compile a specific example,
type "wmake <name of example>" in the examples directory.

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.

if you use watcom you must compile with the -5s option (as done in the
makefile). Hermes has not yet been prepared for -5r.


2.  Implementation details

This port was based on v2.0.21 of the PTC Porting Kit, and version 2.0.2
of the Hermes Porting Kit, and as such any bugs not due to the VBE and
VGA interfacing code are entirely Gaffer's fault :). Bugs due to the VBE
and VGA interfacing are entirely Zoon's fault, because I ripped them out
PTC dos 2.0.6 ;)

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

  taken from ptc dos 2.0.6 by zoon/food:

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 zoon/food for ptc dos 2.0.6, gaffer for
Ptc and Christian Nentwich for Hermes.


5.  Future versions

well, console::flush and console::finish are not implented yet.
Console::read uses getch(), Console::key used kbhit(), and the alt,ctrl
and shift flags are always false. It would be better to use the bios.

Because I have almost finished my school and have to relocate to start
my final trainee ship for 5 months I can't release a new version nor
reply to email because I won't have access to the internet. I hope this
package will inspire someone to continue working. I am afraid that
zoon/flood won't do this as he is working on the Ptc windows package.


6.  Bug reports

better try coders.ptc.bugs on news.scene.org, as I am unable to do
anything.



hope you will enjoy it.

Elemental / Cranium (elemental@chaos.concepts.nl)

