Shawn Lankton Online

Matlab is a great programming language/environment because of its ease of use, great visualization, and rapid prototyping abilities. Raw speed is not one of its strong suits. MEX (Matlab Executables) are the answer. These functions allow you to program in C or C++ (ultra fast languages), but be able to call and use them from Matlab programs. This post is a short intro to mex files which should get you up and running.

What This Post Teaches

In this post, I show how to create a mex file, how to set up inputs and outputs, how to get access to Matlab objects, and how to manipulate them. I also give a skeleton mex program that might be helpful. There is a lot more to learn, and I’d refer you to the mex manual regardless.

What You Should Already Know

I’m going to assume you already know how to program in C, and already know how to program in Matlab. This post does not teach either language, but will show you how to use them together to get the best of both worlds.

Hello world!

Lets get started. First, type:
>>mex -setup
Then go through the menus to select a compiler that you have installed on your system. I use gcc on linux, visual studios on windows, and mexopts on mac. Now, create a file called, “helloworld.cpp” and we’ll start coding. In this first example, pay attention to the signature of the mexFunction. This signature is always the same.


#include <math.h>
#include <matrix.h>
#include <mex.h>

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
  mexPrintf("Hello World!\n");
}


Save the file, and in the Matlab prompt type,
>>mex helloworld.cpp
If all goes well, you should get the following when you run helloworld:
>>helloworld
>>Hello World!

Setting Up Inputs and Outputs

Now that we have a working program, the next step is to get inputs and outputs going so we can do something useful. The mxArray pointers plhs and prhs represent a pointer to the left hand sside and a pointer to the right hand sside respectively. The left hand side are the outputs and the right hand side are the inputs.

put something like this in the top of mexFunction:


  //declare variables
  mxArray *a_in_m, *b_in_m, *c_out_m, *d_out_m;
  const mwSize *dims;
  double *a, *b, *c, *d;
  int dimx, dimy, numdims;
  
  //associate inputs
  a_in_m = mxDuplicateArray(prhs[0]);
  b_in_m = mxDuplicateArray(prhs[1]);
  
  //figure out dimensions
  dims = mxGetDimensions(prhs[0]);
  numdims = mxGetNumberOfDimensions(prhs[0]);
  dimy = (int)dims[0]; dimx = (int)dims[1];
  
  //associate outputs
  c_out_m = plhs[0] = mxCreateDoubleMatrix(dimy,dimx,mxREAL);
  d_out_m = plhs[1] = mxCreateDoubleMatrix(dimy,dimx,mxREAL);


Accessing and Manipulating Matlab Objects

To access the variables, you need to associate a pointer to the data in the mxArray. Once you do this, accessing the variables is very simple.


  a = mxGetPr(a_in_m);
  b = mxGetPr(b_in_m);
  c = mxGetPr(c_out_m);
  d = mxGetPr(d_out_m);


Now it is possible to access the arrays with standard C or C++ [] notation. There are three important things to remember though:

• You use 0-based indexing as always in C
• You still use column-first indexing like in Matlab, though
• To access the arrays, you use linear indexing (you can’t use [x][y], you have to use [y+x*dimy]

With those three things in mind, go crazy. You can use standard C libraries (as long as you include them). You can use for loops as much as your heart desires, and your code will be much, much faster than its Matlab equivalent.

Downloads

Download this starter file (demo.cpp). This has all of the features discussed in this post, and should be a good primer for any mex function. Give it a try. Tell me what you think, and let me know if any improvements are needed.

demo.cpp

To run the demo, download the .cpp file, then at the prompt run:

  >>mex demo.cpp
  >>a = round(rand(2)*10)
  >>b = round(rand(2)*10)
  >>[c,d] = demo(a,b)