Writing a math plugin

The code is written in C++ and MFC. You need Visual Studio 2005 or higher in standard edition as minimum.
The free express edition will not work. (no MFC user dialogs included)

If a special calculation for a actuator axis of a complex simulator is needed, you have to write a short kinetic plugin.
The layout of this plugin type is predefined and you have only to insert the formula for the output and some dialog code.
This section will give you a short overview about the math plugin idea and how you can insert complex calculations in it.
The plugin layout is designed to make simple plugins like “invert” and complex ones like 6DOF control.
A loaded plugin has its own memory area which is only once present and another that is over given by the math settings.
The plugin itself memory area is needed for complex plugins, which are implemented through all axis as a spider web.
Such complex plugins collect the six axis information’s and output the correct six values for each axis in one of the six math axis outputs.

But first we have to begin with a simple plugin. We catch the “percentual scaler plugin” as a sample. The source code for that
plugin is located in the /other stuff/sourcecode/mathplugin directory of your x-sim2 installation folder.
The goal of the percentual plugin is to get the last math line of the profiler2 calculation table and scale it to that value. (bigger/smaller)
So we need a user interaction dialog which ask the user for the percent value and the calculation routine.
Use the scaler plugin source code as a predefined plugin solution and as a SDK for math plugins. It will offer you a dialog solution, which you have only to change to your needs and it offers a good structure for building a math plugin.

Writing a simple sample scaler plugin

You will need some exported functions in a math plugin.
They are:
CALCSETTINGOUTPUT OpenDialog(CALCSETTINGINPUT input);
CALCOUTPUT CalculateValue(CALCINPUT input);
CALCDLLINFO GetDLLType();
CALCLISTENTRY GetListEntry();

GetDLLType() is the first called function of the plugin and gives back the x-sim type of the plugin. Therefore the CALCDLLINFO structure is filled in the init section InitInstance() of the DLL file with the needed information’s. For your own plugin you have to change here the setup to your wishes. Read the comment lines carefully, because the names cannot exceed a maximum of 30 character. Some other values cannot be changed.
Special attention is needed at the ID of the plugin. The ID is fixed, you should choose one number above 100 and tell the author of x-sim the used number. If you choose here the false number it could be identified as another plugin after loading the setup again. You can also ask for a fixed number area, which will be stored by the author of x-sim.
The listentry values will later be shown with the GetListEntry() function. You can only change the names and layout in the init section.
With the OpenDialog() function you can open a user dialog and fill out the 32 available integer values of the settings memory area.
You have to store the number of a used input value (0 to 97 of sender) in the first settings memory integer or let it be fixed to zero.
You will get a “isnew” variable as true that tells you if this is a new inserted plugin in the math list so you can fill the dialog with standard values.
Each added plugin has its own shared memory section, 32 integer for setting values and 32 integer of secondary storage area.
This values you will need if the profiler calls the plugin CalculateValue() function. This function will get the settings and storage memory.
You can use the storage integer to store the last results that are needed in the next result or to store some states. The settings 32 integer
will be transfered to show the wished user setting in a plugin but can be resized if some setting value has increased.
The 32 settings integers will be stored to a setup file, the secondary storage integers will be zero on a program startup or a plugin insert / load.
In the CalculateValue() area you can make all your code to transform the input value to a output value like the sample shows you.
For timing dependend operations you will get the current math thread rounds per second which represents the CalculateValue() function calls
in one second. Here you can divide your passed time with 1/rounds. It is possible that this rounds change in a second because you are using a
throttling processor in your system or you add another plugin which will use some processor time. Make it dynamically.
You will receive a sender input value if you have placed the sender value number in the first of 32 settings integer value as described above.
After the calculation area you have to generate a output response which holds the new settings values (normally the same) and the secondary
32 integer values which stores the values to the next math round:
for(int z=0; z < 32; z++){output.sharedmemory[z]=input.sharedmemory[z];output.settingvalues[z]=input.settingvalues[z];}

Additionally notes:
-If you work with float values in the 32 integer values of settings or secondary memory area, you have to typecast the four integer bytes to the four float values.
-The math thread of the profiler is step by step oriented, so the CalculateValue() function are never called twice.
-Do not store secondary values in the DLL shared memory area because the dll file CalculateValue() function is called with different user settings of different math lines of the profiler math setup section.
-The first icon in the plugin DLL file is used to be displayed in the math list box. Exchange that 16x16 icon, if you like to insert a different picture.