README for the WinPic Interface Plugin directory
------------------------------------------------

Author: Wolfgang Buescher
Date:   2008-05-06 (YYYY-MM-DD)
Original file location: ..\WinPicpr\interface_dll_sources\readme.txt

  Chapter overview :
  - Introduction
  - Writing your own hardware interface plugin
  - The "Demo" interface
    
 


Introduction
-------------------------------------------

The hardware interface plugins explained in this document 
can be loaded by WinPic to support "exotic" hardware interface,
for example interfaces which are neither connected to the serial
or parallel port.

The sourcecodes of a sample DLL can be found on the author's
website (search the net for "DL4YHF WinPic", there is a link
to the interface-plugin-DLL in the "Download" section).



Writing your own hardware interface plugin
-------------------------------------------

Hardware interface plugins for WinPic filter can be written with 
any C compiler. This directory contains a simple example for 
such plugin, designed to work with a "JDM2" adapter .
It has successfully been compiled with the following compilers:
 - DevCpp Version 4.9.9.2
 - Borland C++Builder V4.0 (primarily used for development) 

To write your own hardare interface DLL, download the file
 "interface_dlls.zip", and unpack the contents of the folder
 "interface_dlls" into the folder of the same name, which has
 been created when installing WinPic on your PC. 

All "mandatory" DLL functions, along with their function prototypes,
are declared in the header file PHW_intf_dll.h . It also contains
the definition of the data type T_PHWInfo (hardware-interface-info),
which will be passed (via pointer) to most functions in the plugin.

CAUTION: The members of that structure may change in future !
  To avoid compatibility issues with newer versions, the size of
  the structure is part of the structure itself, so any plugin
  can check if it's still 'compatible'. New members will always
  be APPENDED to the end of the structure, so existing members
  will always keep their address offset within the structure.

To avoid duplicated information here, study the header file and the
sample application ("hw_intf_demo_1.c"). Especially the header
is heavily commented; in fact those comments will always be the most
up-to-date information about the hardware interface DLL.

Basically, the DLL only needs to contain the following functions:
  (btw the module prefix "PHW" stands for "Programmer Hardware")

PHW_Init()  :  Called once by the host (=WinPic for example), 
               before the real-time processing starts.
               This is the place where your plugin can
               allocate its own (internal) resources,
               or open a control window ("GUI") of its own.

PHW_Exit()  :  Called once by the host to stop processing, 
               or when terminating.

PHW_OnTimer() : Periodically called from WinPic's main thread 
               (not from any "worker thread" ) .
               The calling interval is approximately 200 ms, 
               but DON'T RELY ON THAT : The caller is a normal
               "windows" timer.

PHW_SetVpp(), PHW_SetVdd(), PHW_SetClockAndData(), ... :
               Low-level programming functions for "simple" 
               programming interfaces .



Since the plugin-API is still under construction (as of 2008-05),
it may happen that the plugin-info-structure
T_PHWInfo (defined in PHW_intf_dll.h) has been changed.
In that case, sizeof( T_PHwInfo ) is *NOT* equal to
the component 'iSizeOfStruct' in T_PHWInfo . The host
(=WinPic) sets iSizeOfStruct to sizeof(T_PHWInfo),
before passing a pointer to this structure to PHW_Init().
PHW_Init() must return PHW_ERROR_VERSION_INCOMPATIBLE if
sizeof(T_FftFilterInfo) is not equal to pInfo->iSizeOfStruct .
In that case, you will see the following message on SpecLab's
FFT-filter plugin tab :

   Error: PLUGIN VERSION INCOMPATIBLE !

In that case, make sure you have the latest version of SpecLab
running on your PC, and recompile your plugin with the latest
version of PHW_intf_dll.h .  After that, everything should be
fine again ;-)



Plugins with their own user interface
-------------------------------------------

For plugins which require graphic output in their own window,
or more advanced controls, you can implement your own control
window. The demo plugin contains a very basic
display window, which does almost nothing so far.
There is a helper module called "PHW_framework1.c" 
 (PHW_ = file prefix for 'Programmer HardWare Plugin") ,
which contains some framework for a simple display window
which only uses basic Win32 API calls (without MFC, VCL, etc).
Of course, you may as well write implement the control window
in any programming language, using any development environment,
or "toolbox" for a graphic shell, but that is outside the scope
of this document. The advantage of using only Win32 API
calls to implement a GUI is that it works with different 
compilers & IDE's, but it can be terribly confusing to dig
your way through the Win32 API reference (which, by the way,
is one reason why Borland's VCL, and later Microsoft's MFC
got so much popularity). But back to the (win32-)basics:

To create its own window, the plugin must first register
a 'class' for its window (hasn't got anything to do with C++),
using the Win32 API function RegisterClassEx(), and then open
such a window with CreateWindow() .  To do this, we need a few
parameters which are -for that purpose- contained in the
T_FftFilterInfo structure which is passed from the host 
(WinPic) as pointer "pInfo" to all functions in the DLL. 
Most important to create your own GUI are :
  pInfo->dwhAppInstance :
       HINSTANCE to application instance, set by HOST(*)
  pInfo->dwhMainWindow  :
       HWND to the application's main window, set by HOST.
  pInfo->dwhPluginWindow:
       handle to the plugin's own window, set by PLUGIN if used.
       See notes in the sample plugin about when and how
       to close the plugin's window !
  pInfo->sz40WinClassName[44] :
       Must be set to a unique "class name" for the plugin's 
       own window. Set by PLUGIN. Caution: If two different
       plugins use the same class name at the same time,
       the second will fail to open its control window !

  pInfo->iPluginWindowX, iPluginWindowY, 
         iPluginWindowWidth, iPluginWindowHeight
       Position and size of the plugin's window .
       These values are initialized by the host, and saved
       in SL's configuration file between two sessions.
       But the plugin may overwrite these values if it thinks
       the window is too small, too large, etc.
       If the plugin uses "FFP_framework1.c", it should
       modify these parameters *before* it calls
       PHW_OpenControlPanel() to create+open its own window.


 (*) In this context, the HOST (which loads the plugin DLL) 
     is WinPic, or a similar application using the same
     plugin interface .


Shortly before the plugin is unloaded by the HOST, the function
PHW_Exit() is called. In this function, the plugin must close
the window which it has created for this instance, and -if 
it was the last instance running- unregister the window class name
using the Win32 API function UnregisterClass() . 
If you use the helper module "PHW_Framework1.c", you can easily 
do all this by calling PHW_DestroyControlPanel(pInfo) 
from PHW_Exit(pInfo) in your plugin's main module .
PHW_DestroyControlPanel will automatically destroy the plugin's
control panel, and unregister the window class name if it was
the last running instance of the plugin.

Note: If you write the GUI for your plugin on a "higher level",
   for example using Borland's VCL or some other "visual" tool,
   do *NOT* close and destroy your window with a Win32 API call !
   Refer to the manual of your "visual" development system,
   whatever that may be ... Borland Builder: use the TForm class.




The "Demo" plugin
-------------------------------------------


Up to now, the demo plugin only demonstrates...
 

 - how to create a simple custom control panel, using
    only plain Win32 API calls (and Framework1.c) .









// EOF

