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__,
and the signature define for the PTC Win32 extensions is
__PTC_WIN32_EXTENSIONS__. 

If you choose to use any of the extensions below, you should
make sure that you wrap the code with #ifdef __PTC_WIN32_EXTENSIONS__
to ensure that your code will still be portable. 

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

Here is the list of extension functions that are provided by
OpenPTC 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 BACK SURFACE of 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
   (ie. the actual primary surface, not the back buffer
    of the primary surface, or the secondary 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) void open(HWND window,int pages = 0);
   void open(HWND window,const Format &format,int pages = 0);
   void open(HWND window,int width,int height,const Format &format,int pages = 0);
   void open(HWND window,const Mode &mode,int pages = 0);

- This group of open functions allow you to create and manage
  the display window yourself instead of having the ptc console
  manage the window for you.
- See the extensions example "WndProc" for an example of how
  to do this.
- It is highly recommended that you let the console manage the
  window for you unless you absolutely need to manage the HWND
  yourself. For example, if all you need is access to some
  window messages, you can get this by using SetWindowLong to
  install your own WndProc that does what you need, then calls
  the old one (ptc wndproc). Soon i'll put an extension example
  in to show how to do this. sit tight :)


8) 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.
