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

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. I did this because Hermes 1.2.2 and above aren't compatible 
with ptc dos 2.0.6.


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.3 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. For easy
living this already has been done for you. 
I had to add the following lines in headx86.h in the watcom section:
#pragma aux ConvertX86p16_32RGB888_LUT_X86 "_*";
#pragma aux ConvertX86p16_32BGR888_LUT_X86 "_*";
#pragma aux ConvertX86p16_32RGBA888_LUT_X86 "_*";
#pragma aux ConvertX86p16_32BGRA888_LUT_X86 "_*";

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. For the release version type
"wmake config=release". To compile the examples type "wmake" in the
examples directory. To compile a specific example, type
"wmake <name of example>" in the examples directory. This is not valid
for the stretch and key example. You have to go to the valid directory
and type "wmake".

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 have troubles compiling with nasm under windows because it
runs out of memory change the nasm command in the makefiles to nasmw.

if you use watcom you MUST compile with the -5s option (as done in the
makefile). Hermes 1.2.3 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 ;). Anything else is covert by the GNU licence. So i am not
responcible for anyting ;).

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. As of 2.0.8 a keyboard extension has been added
also. Console::isKeyPressed(int code) checks if a key has been pressed.

A note about the keyboard implementation: 
This is an extension of PTC, so it is not compatible with other ptc
packages since they miss the function Console::isKeyPressed(). The
reason why I added this whas that PTC can't check for multiple key
pressed like arrow up and down. I talked with Gaffer about this and
he said: "ptc is a graphics library with simple console style key 
presses... not complex input handling. where does it stop? if i add 
advanced key press checking, do i add mouse support too? how about 
joystick support? ... i had to draw the line, and thats where it is.
basically, there is a need for a supporting library to step in and 
provide advanced portable keyboard (asynchronous style like you want)
operations on top of PTC. somebody else can do it, it doesnt belong 
inside the PTC core." So i added it... BUT IT DOESN'T BELONG INSIDE
THE PTC CORE... it's an extension... ONLY for ptc dos. Hope i haven't
upset someone. Hope i have inspired some to build that support library ;)


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.
"no keyboard interrupt" - disables keyboard interrupt hook.


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

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)

