SigmaPiHost DLL version Alpha 5

PSP compatible plug-ins (filters) host for BCB/Delphi 
Supported plugins type: 8BF



Functions:
	

 *   void sph_HostLoad()

     -  Load SigmaPiHost DLL.  Must be called once prior to other functions call.

  
 *   void sph_HostCreateObjects()

     - Create host objects. Must be called once after load function.

 
 *   void sph_HostDestroyObjects

     - Destroy host objects. Must be called once before unoload function.


 *   void sph_HostUnLoad()

     - Unload SigmaPiHost DLL. Must be called once befor end of application, or when
     host DLL is no longer needed.


 *   void sph_HostAbout()
   
     - Displays current host version.


*   void PlugInEnumerateCBF(AnsiString PI_directory, bool scan_subdirs, ENUMCALLBACK enum_func)

    - performs plug-ins enumeration.

    Call back function ENUMCALLBACK enm_func(char *) returns pointer to string (char *) which contains
    four fileds delilited with '\n' character. 

    Following fields (informations) are contained in every string returned:

	    1) Filter category  -  usually used as a drop down menu item.
	    2) Filter name      -  usaully used as a drop down submenu item.
	    3) Filter entrypoint name - used for plug-in loading (8bf entry point).
	    4) Filter file name -  filter file name with path. Used to execute desired filter.

     
*   void sph_PlugInAbout(HostRecord *hRecord)

   - displays plug-in about box if available.


*  bool sph_PlugInLoad(char *PI_file_name, char *PI_entry_point)

   - load plug-in by it's filename and it's entry point name. Returns true if plug-in successfuly loaded.

   

*  bool sph_PlugInRunBMP(HostRecord *hRecord)
   
   - run last loaded plug-in (filter). Input parameters: pointer to HostRecord structure.
   After execution on desired area defined by filter_rectangle or/and mask, resulting bitmap
   is copied over source bitmap.



Usuall calling sequence:

   #include "SigmaPiHost.h"
   .
   .	
   sph_HostLoad();		// Always the first.
   sph_HostCreateObjects();     // MUST BE always after load.
   .
   .
   .
   // enumerating plug-ins and creating drop down menu or filling listboxes (see examples)
   .
   .
   .
   // prepare and fill HostRecord structure that will be passed to SigmaPiHost DLL       
   .		
   .
   .
   if (sph_PlugInLoad(FilterName))
      {
      if (!sph_PlugInRunBMP(&hRecord)
         // error running filter - return or display message
         return false;
      }              
         
   sph_HostDestroyObjects();   // MUST BE always befor unload.	
   sph_HostUnLoad();	       // Always unload when not needed.				
   .
   .
   .



   

HostRecord structure:

   
   This is main SigmaPiHost DLL structure and all user supplied data are passed to SigmaPiHOst DLL
   through this structure.


   typedef struct HostRecord
        {
        bool has_bounding_rectangle;
	//
	// Does image have bounding rectangle? Used to filter a part of image. 
	//
        TRect filter_rect;
	//
	// Filter rectangle coordinates. When bounding rectangle is true, user must fill up
	// left, right, top and bottom coordinates of bounding rectangle.
	//
        Graphics::TBitmap *src_bitmap;
	//
	// Pointer to source bitmap. This bitmap will be updated by filtered pixels.
	//
        Graphics::TBitmap *input_mask_bitmap;
	//
	// Pointer to input mask bitmap. Grayscale bitmap (8-bit depth) passed to filter. If filter support
	// masking, it will use this mask. Mask content is not altered by filter.
	//
        Graphics::TBitmap *output_mask_bitmap;
	//
	// Pointer to output mask bitmap. Grayscale bitmap (8-bit depth) passed to SigmaPiHost DLL.
	// Usually same as input mask pointer. This mask is used after image is filtered.
	// If filter does not support masking, resulting image will be masked using output mask.
	// If filter supports masking, this mask for additional effects. Output masking depends
	// on output masking options.   
	// 
	//
        int output_masking_option;
	//
	// Output masking options. When output mask pointer is supplied, output masking
	// depends on parameter set in this field:
	// 
	//   omStandard   -  this option tells SigmaPiHost to perform standard output masking and this is:
	//	             a) If plugin filter supports input masking, output area is hard masked, i.e.
	//                      filtered pixels are coppied to source bitmap with 0 transparency. 		   
	//		     b) If plugin filter does not support input masking (FileFactory filters),
	//                      filtered pixels are copied to source bitmap using output mask
	//                      as alpha channel.		
	//
	//   omForceSoft  - this option tells host to always force soft masking no matter does plugin support
	//                  input mask or not. Filtered pixels are copied to source bitmap using output mask as
	//                  alpha channel.
	//
	//   omForceHard  - this option tells host to always force hard masking. Filtered pixels are coppied
	//                  to source bitmap with 0 transparency, i.e. if mask byte is > 0 resulting pixel is coppied
	//                  to source bitmap, otherwise not.
	//
        TColor foreground_color;
	//
	// foreground color
	//
        TColor background_color;
	//
	// background color
	//
        PROGRESSCALLBACK progress_proc;
	//
	// Progress call back function. It accepts two parameters (long done, long total).
	// Used to show and update progress indicator, when plugin is executed.
	//
	HWND hWnd;
	//
	// pointer to hosting application/form window handle.
	//
        char reserved[256];
        } HostRecord;
	

Nown bugs and further development:

   
   1) Some filters still can not be executed or behave very strange.
   


