Using Templates to Call External Functions

For this next example we are going to use a template to collect some data and then have the template call a function in an external application library. The order of events will be similar to the following:

User -----> VX                  : User selects button, command=!template

            VX                  : VX process template

User <----> VX                  : Template defines data to collect

            VX -----> AppLib    : Template calls application

            VX <----> AppLib    : application accesses collected inputs

                             AppLib    : application processes collected inputs

            VX <----- AppLib    : application updates DB

            VX                  : VX waits for next command

For the first example, we are going to create a sphere of a specified radius which interpolates three points.

Looking at OpenVxUser.t, our user menu template, we have the following:
 

Since we are using the "!" operator VX is going to look for a template named "OpenVxSph3" to process.  This is a local template residing in OpenVX/supp along with the user menu template.

In order for VX to process this template you must have already compiled it into Forms.VX.

One purpose of the template is to tell VX what data to collect.  This template has several FIELD sections each of which correspond to data that will be collected from the user.  We need the radius of the sphere and the three points to interpolate.  Notice that there is a line marked "trigger" and then a fifth field.  This last field allows the user to pick which side the center of the sphere should be on.  This is not something that you want to always be asked.  Any fields which occur after the trigger command will appear as option buttons.  That is these fields will not be prompted for unless the user picks the command option button from the VX topbar.  You cannot have more than four "option" buttons associated with a single command.

The template file also contains the line "function=ovxSph3Pt".  This tells VX what function to call after the data has been collected.  Notice that in this case ovxSph3Pt() is a function in our new external library.  How does VX know where to find this function?  If you look at VxOvxInit() in the file VxOvxUtils.c you will see that we added the function call:

This call told VX that ovxSph3Pt was in fact a function in our new library.  Note: all functions called by the "function=..." template command are assumed to have the same parameter list.
 

When VX collects user input it creates a database object which stores this information.  The index of this database object is passed in through the first integer parameter, "idx_in". Inside of this data collection object data is further separated based on the id which was assigned to the data in the template file.  Thus for example in the template file we have:

If an application want to get hold of this second point it will need the index of the data collection object which is passed in to the high level function and it will need to know what id was assigned to that data in the template.

This means that the high level application routine which wants to use the data collected by VX is closely tied to the template that called it.  On the other hand it means that the template can be modified and the order of items can be shifted around without affecting the application (as long as the id remains unchanged).

Several functions have been provided in OpenVX to help the application retrieve the data that VX has collected.  Look at OpenVX/src/ovxSph3Pt.c the source file for the function ovxSph3Pt(). You will see calls to VxInpDst( idx_in, idFld, ...) and VxInpPnt( idx_in, idFld, ...) to get the radius and point data respectively.  In both cases they must pass the index of the data collection object and the field id to VX in order to get the correct data back.

Finally the application processes these inputs and adds the new sphere to the VX database. See Adding Objects to VX DB for more detail on adding objects to the database.