3 MEX-files

Extended Features
Future Direction

Table of Contents:

MEX files are used to allow subroutines implemented in C or C++ to be ran in Matlab as if they were built-in functions or M-files. Therefore, compilation of a C++ program as a MEX-file will generate dynamically linkable subrountines (i.e., a .dll file). In the spider application, the .dll generated is called 'cmex.dll'. For in-depth reading on how MEX-files are generated, see discussion in Appendix 2.

There are functions and semantics that make MEX-files unique from C++ programs. This page outlines the differences and discusses the interface between Matlab and the OpenGL/Visual C++ program.

3.1 Opengl/Visual C++ Specifics

The following additions need to be made to the opengl/Visual C++ program in order to be able to compile the program into a MEX-file:

	#include "mex.h"
	// instead of a main() function, mexFunction() is used as the gateway
	void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]) {
The mexFunction replaces the main() function that is normally found in the C program, and consists of the following parameters:
  • nlhs - # of left hand side arguments
  • plhs - pointer to left hand side arguments
  • nrhs - # of right hand side arguments
  • prhs - pointer to right hand side arguments
  • The inputs are the right hand side arguments, while the outputs to the program are the left hand side arguments. Thus, all input of morphology and animation parameters are passed from the matlab gui program in an array form and appear as a prhs mxArray structure in the Visual C++ program. One downside of this method is that the ordering of the parameters become particular important since elements are assigned according to their position in the mxArray.

    Since the mxArray is a special structure that contains Matlab data, I extract only the numerical value of the mxArray elements (by using the mxGetScalar() function). I then proceed to assign global parameters in the OpenGL program to the settings found in the prhs mxArray:

    void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]) {
    	int		i;
    	for (i = 0; i < nrhs; i++) {
    		inputParams[i] = mxGetScalar(prhs[i]);
    	numParams = nrhs;
    	// Set all the parameters and dimensions of the spider geometry.
    Each of the set*Colors() and set*Params() functions above set global variables to a particular inputParams[i] value. Once this was done, the rendering of the spider can read values specified by these global variables.

    Upon GUI interaction from the Matlab end, these values are constantly changed. Every user interaction that occurs from the Matlab GUI resets all these global variables to the values specified in the prhs mxArray[].

    3.2 Matlab Specifics

    I created a variable called 'vars' that is essentially global since it is always updated and contained in the 'userdata' section of the 'Spider GUI' window:

    vars = 
                myname: 'spider_gui'
         spline1button: 29.0006
         spline2button: 30.0006
         spline3button: 31.0006
         spline4button: 32.0006
              filename: 33.0006
           splineIndex: 1
                  tmax: 120
            NumControl: 120
                   FPS: 30
        ForceZeroSlope: 1
            AngleRange: 60
                     t: [1x120 double]
                    tt: [1x3600 double]
            numSplines: 4
                     y: [120x4 double]
                    yy: [3600x4 double]
                    sp: 90.0005
                 line1: 39.0012
             mousedown: 0
                values: {1x633 cell}
                 names: {1x153 cell}
    The main parameter to take note of in this structure is vars.values since this is the array that controls all spider morphology and animation, and is passed into the MEX-file for processing. There are a total of 633 data points contained in vars.values. The first 152 data points track color and morphology of the spider, while the other 481 points track the animation of the spider (i.e., 120 points track each timestep for one angle/joint. Since there are 4 joints, this adds up to 480 points which track the leg motion. The last data point is used to track the maximum number of time steps that can occur).