OpenPTC 1.0 Win32 Distribution Extensions
-----------------------------------------


The core platform independent standard of OpenPTC 1.0
exposes a lot of common functionality across a large
range of different graphics platforms.

However, some things, no matter how useful, just dont
make any sense in a platform independent standard so
they have been left out.

So that users of PTC can still have full access to the
underlying graphics platform, each distribution implements
extensions to the standard. These extensions are protected
by a signature define for portability.

The signature define of this PTC distribution is __PTC_WIN32__.
If you choose to use any of the extensions below, you should
make sure that you wrap the code with #ifdef __PTC_WIN32__
to ensure that your code will still be portable. 

You can also use the signature define to wrap around the 
WinMain and main so that your application is compilable
on Win32 and other platforms without any changes.

Here is a list of extension functions that are provided by
PTC for Win32:


1) HWND Console::window()

 - this function returns the current window handle of the
   console.
 - this interface is only valid between open and close.
 - be careful what you do with the window handle, as you 
   may cause problems with normal PTC operation if you do
   not know what you are doing.


2) LPDIRECTDRAW Console::lpDD()
 
 - this function returns a pointer to the current direct draw
   interface.
 - this interface is only valid between open and close.
 - you should not use the lpDD, instead use the lpDD2 below.
 - be careful what you do with this interface, as you may
   cause problems with normal PTC operation if you do not
   know what you are doing.


3) LPDIRECTDRAW Console::lpDD2()

 - this function returns a pointer to the current direct draw 2
   interface.
 - this interface is only valid between open and close.
 - you should use the lpDD2 instead of lpDD.
 - be careful what you do with this interface, as you may
   cause problems with normal PTC operation if you do not
   know what you are doing.


4) LPDIRECTDRAWSURFACE Console::lpDDS()
 
 - this function returns a pointer to the current direct draw
   primary surface, or, if a secondary surface exists, it
   returns a pointer to that surface instead.
 - this interface is only valid between open and close.
 - be careful what you do with this interface, as you may
   cause problems with normal PTC operation if you do not
   know what you are doing.

5) LPDIRECTDRAWSURFACE Console::lpDDS_primary

 - this function returns a pointer to the primary surface
 - this interface is only valid between open and close.
 - be careful what you do with this interface, as you may
   cause problems with normal PTC operation if you do not
   know what you are doing.

6) LPDIRECTDRAWSURFACE Console::lpDDS_secondary

 - this function returns a pointer to the secondary surface
 - the return value is NULL if a secondary surface does not
   exist. typically secondary surfaces exist in windowed
   output and in some special fullscreen output modes.
 - this interface is only valid between open and close.
 - be careful what you do with this interface, as you may
   cause problems with normal PTC operation if you do not
   know what you are doing.

7) Are there any missing extensions?

 - Do you require any other extension functions to make the most
   out of PTC for Win32? 
 - If so, post a request to the newsgroup news.scene.org/coders.ptc
   and we will see what we can do about it as soon as possible.
