Windows DLL Extension

Please be sure to read the Overview page to get a general sense of if the Windows DLL RoboRealm Extension is a good fit for you.

Extending RoboRealm using a windows DLL is the best way to introduce new functionality into RoboRealm.

To create your own dll extension download our example dll program. This example program (SwapColors) will swap the Red and Blue pixel colors in an effort to show how image modifications can be performed. Note that the download also includes the Pipe and Socket example implementations.

You will need VC++ or other C++ compiler to build the program.

Note that a pre-built executable is in the Release subfolder.

To try the example SwapColor extension click on the Extensions->SwapColor module. This shows a very basic module that provides a GUI interface that can be used to capture user configuration options.

The first extensions (VBScript_Program, Pipe_Program, etc) are added to the tree menu by default. Afterwards the custom DLL module names will appear. In your current case only SwapColor exists. If you look in your RoboRealm folder you will notice a file call extensions.xml which looks something like:

<extensions>
    <extension>
        <name>SwapColor</name>
        <dll>RRModule.dll</dll>
    </extension>
</extensions>

When you create more modules add an additional entry to this XML file as such:

<extensions>
    <extension>
        <name>SwapColor</name>
        <dll>RRModule.dll</dll>
    </extension>
    <extension>
        <name>NewModule</name>
        <dll>NewModule.dll</dll>
    </extension>
</extensions>

To create your own DLL module use the existing SwapColor example or use VC++ to create a new DLL project.

There are several files in the DLL folder. The following are its contents and function:

• HashtableExt - interface class used to provide access into the RoboRealm variable table.
• ModuleDlg - interface class that specifies a RoboRealm module. All of your modules must have this class as its base.
• RoboRealmExt - interface class used to communicate directly back to RoboRealm
• RRModule - container for the DLL
• SwapColorDlg - the actual code for the image processing function to be performed

The main focus of the DLL will be in SwapColorDlg class. This file contains the code to perform the image manipulation routines. There are several calls that RoboRealm makes that you can trap and add functionality. See ModuleDlg.cpp for an explanation of those routines.

For example, the main routine is

int SwapColorDlg::Process(unsigned char *data, short int *tmpImage, unsigned char *tmpImage)

which is called to process an image. The first parameter is the image data. The second two are temporary buffers that can be used when processing the image. Often an images are processed in destructive ways so a copy needs to be made during processing. Any modifications to the data array will reflect in the actual image displayed by RoboRealm after being passed to all other modules after yours.

Variables

Two types of variable are available to the RoboRealm DLL module. The first is also known by VBScript, Pipe and Socket extensions which are the RoboRealm variables. These variables are shared amongst all RoboRealm modules and can be accessed at any time. Their purpose is to store relevant image information needed to perform processing or for communication between modules.

The second type of variable is the configuration variable that is used to store the configuration specified by users as they interact with the provided module's GUI. It is your responsibility to save this information so that on recall the interface will appear as last configured. This is also needed during program invocations so that users do not need to reconfigure modules during every usage.

Use the SetInt, SetFloat, SetString calls to perform this. See ModuleDlg.dll for additional details.

Things to remember:

• If your DLL crashes it will crash the RoboRealm program too!
• You MUST compile your DLL in Release mode. RoboRealm uses virtual classes to simplify interfacing to the DLL. If you compile your DLL in DEBUG mode the class declarations will NOT be in the same memory alignment as RoboRealm.
• When recompiling your DLL you will need to terminate RoboRealm in order for the new DLL to overwrite the existing one. Simply closing RoboRealm will allow it to remember your current configuration (saved in working.xml) and reloaded when you re-run the application. This should minimize the number of clicks in write, compile, and test programming cycles.