At the end of the C-code framework file created by the Data Explorer Module Builder is a "worker routine" that serves as an interface to the user's application code. The entry point to this routine (i.e., its name) consists of the module name affixed to "_worker" (e.g., the name of the worker routine for the X module is X_worker).
The Module Builder prepares a parameter list for the worker routine that contains information from the module input parameters, along with pointers to memory for module results. Three examples appear in "Worker Routine Examples". In each example, the Module Builder creates a module with two inputs (the first a Field/Group, and the second a Value) and one output (a Field/Group Object).
If the worker routine needs information about the positions component of the first input parameter, it will use one of two sets of arguments to define that information, depending on whether the request is for regular or irregular positions:
Regular positions arguments: int p_knt Total number of positions int p_dim Dimensionality of positions int *p_counts Count of positions along each dimension float *p_origin Origin of regular grid float *p_deltas Delta vectors, p_dim x p_dim Irregular positions arguments: int p_knt Total number of positions int p_dim Dimensionality of positions float *p_positions Explicit list of positions
If the worker routine needs information about the connections component of the first input parameter, it will use one of two sets of arguments for defining that information, depending on whether the request is for regular or irregular positions:
Regular connections arguments: int c_knt Total number of connections elements int c_nv Number of vertices per element int *c_counts Count of vertices along each dimension
Irregular connections arguments: int c_knt Total number of connections elements int c_nv Number of vertices per element int *c_connections Explicit list of connections elements
For each input to the module, a count value and a pointer are sent to the worker routine. These arguments are named by appending _knt and _data respectively to the parameter name given in the Individual Parameter Information section of the Module Builder interface. Thus, for an input parameter named param1, the worker routine would add the following to its argument list:
int param1_knt The number of elements in the parameter.
type *param1_data A pointer to the data associated with the parameter.
The pointer type is that specified in the Data type
field of the Individual Parameter
Information section of the
Module Builder.
For a Field/Group input, these arguments reflect the contents of the "data" component of the leaf. For a Value input (which must be a Data Explorer Array), they reflect the contents of the parameter. Because the parameters are inputs to the module, the arguments are read-only.
For each output of the module, a counts value and a pointer are sent to the worker routine. These arguments are named by appending _knt and _data respectively to the parameter name given in the Individual Parameter Information section of the Module Builder dialog box. Thus, for an input parameter named param2, the worker routine would add the following to its argument list:
int param2_knt The number of elements in the parameter.
type *param2_data A pointer to the data associated with the parameter.
The pointer type is that specified in the Data type
field of the Individual Parameter
Information section of the
Module Builder.
For a Field/Group output, these arguments reflect the contents of the "data" component of the leaf (if the leaf is a Data Explorer Field) or of the array itself (if the leaf is a Data Explorer Array). For a Value input (which must be a Data Explorer Array), they reflect the contents of the parameter. The memory associated with these parameters is not initialized.
If an input parameter is not provided, the corresponding counts argument of the worker routine for that parameter is zero (0). Implementing the default for the input parameter is the function of the worker routine.
Figure 5. Worker Routine:
Example1_worker. This routine requests no positions or
connections.
int
Example1_worker(
int inputObject_knt, float *inputObject_data,
int inputArgument_knt, float *inputArgument_data,
int outputObject_knt, float *outputObject_data)
{
/*
* The arguments to this routine are:
*
* The following are inputs and therefore read-only. The default * values are given and should be used if knt is 0. * * inputObject_knt, inputObject_data: count and pointer for input "inputObject" * no default value given. * inputArgument_knt, inputArgument_data: count and pointer for input "inputArgument" * nondescriptive default value is "1.0" * * The following are outputs and therefore writable. * * outputObject_knt, outputObject_data: count and pointer for output "outputObject" */ /* * User's code goes here. */ }
Figure 6. Worker Routine.
Example2_worker. This routine requests regular positions and
connections.
int Example2_worker( int p_knt, int p_dim, int *p_counts, float *p_origin, float *p_deltas, int c_knt, int c_nv, int *c_counts, int inputObject_knt, float *inputObject_data, int inputArgument_knt, float *inputArgument_data, int outputObject_knt, float *outputObject_data)
{
/*
* The arguments to this routine are:
*
* p_knt: total count of input positions
* p_dim: dimensionality of input positions
* p_counts: count along each axis of regular positions grid
* p_origin: origin of regular positions grid
* p_deltas: regular positions delta vectors
* c_knt: total count of input connections elements
* c_nv: number of vertices per element
* c_counts: vertex count along each axis of regular positions grid
*
* The following are inputs and therefore read-only. The default * values are given and should be used if knt is 0. * * inputObject_knt, inputObject_data: count and pointer for input "inputObject" * no default value given. * inputArgument_knt, inputArgument_data: count and pointer for input "inputArgument" * nondescriptive default value is "1.0" * * The following are outputs and therefore writable. * * outputObject_knt, outputObject_data: count and pointer for output "outputObject" */ /* * User's code goes here. */ }
Figure 7. Worker Routine.
Example3_worker. This routine requests irregular positions and
connections.
int Example3_worker( int p_knt, int p_dim, float *p_positions, int c_knt, int c_nv, int *c_connections, int inputObject_knt, float *inputObject_data, int inputArgument_knt, float *inputArgument_data, int outputObject_knt, float *outputObject_data)
{
/*
* The arguments to this routine are:
*
* p_knt: total count of input positions
* p_dim: dimensionality of input positions
* p_positions: pointer to positions list
* c_knt: total count of input connections elements
* c_nv: number of vertices per element
* c_connections: pointer to connections list
*
* The following are inputs and therefore read-only. The default
* values are given and should be used if knt is 0.
*
* inputObject_knt, inputObject_data: count and pointer for input "inputObject"
* no default value given
* inputArgument_knt, inputArgument_data: count and pointer for input "inputArgument"
* nondescriptive default value is "1.0"
*
* The following are outputs and therefore writable. * * outputObject_knt, outputObject_data: count and pointer for output "outputObject" */ /* * User's code goes here. */ }