18.1 Writing c functions in matlab (mex-files)

Introduction

The MATLAB M-File is very good for putting together functions or scripts that run many of MATLAB's fast Built-In functions. One nice thing about these files is that they are never compiled and will run onany system that is already running MATLAB. MATLAB achieves this by interpreting each line of the M-File every time it is run. This method of running the code can make processing time very slow forlarge and complicated functions, especially those with many loops because every line within the loop will be interpreted as a new line, each time through the loop. Good MATLAB code avoids these things by usingas many Built-In features and array operations as possible (because these are fast and efficient). Sometimes this is not enough...

MATLAB has the capability of running functions written in C. The files which hold the source for these functions are called MEX-Files. The mexFunctions are not intended to be asubstitue for MATLAB's Built-In operations however if you need to code many loops and other things that MATLAB is not very good at, this is a good option. This feature also allowssystem-specific APIs to be called to extend MATLAB's abilities (see the Serial Port Tutorial for an example of this).

This document is arranged in the following manner:

• The MEX-Function: Interface to MATLAB
• Getting and Creating Data
• Calling Built-In Functions from a MEX-File
• Compiling
• Useful Functions not Mentioned Here

The mex-function: interface to matlab

When writing programs in C, it is always assumed that the program will start execution from the main(). MEX -Files are similar in that they always start execution from a special function called the mexFunction.This function has return type void and is the "gateway" between the MATLAB function call, and your C code.

In order to make a mex-function, you must include the "mex.h" library. This library contains all of the APIs that MATLAB provides. There are four input parameters to the mexFunction whichcorrespond to the way a function is called in MATLAB - (ex: [z0,z1] = jasonsFunction(x,y,z); )

• nlhs (Type = int): This paramter represents the number of "left hand side" arguments. So in my example function call, nlhs = 2 (the outputs are z0 and z1).
• plhs (Type = array of pointers to mxArrays): This parameter is the actual output arguments. As we will see later, an mxArray is MATLAB's structure for holding data and each element in plhs holds an mxArray of data.
• nrhs (Type = int): Similar to nlhs, this paramter holds the number of "right hand side" arguments.
• prhs (Type = const array of pointers to mxArrays): This array hold all of the pointers to the mxArrays of input data for instance, prhs[0]holds the mxArray containing x, prhs[1] holds the mxArray containing y, etc).