Next: Character Strings in Mex-Files, Previous: Getting Started with Mex-Files, Up: Mex-Files [Contents][Index]
The basic mex type of all variables is mxArray. Any object,
such as a matrix, cell array, or structure is stored in this basic
type. As such, mxArray serves basically the same purpose as the
octave_value class in oct-files in that it acts as a container for the
more specialized types.
The mxArray structure contains at a minimum, the name of the
variable it represents, its dimensions, its type, and whether the variable is
real or complex. It can also contain a number of additional fields
depending on the type of the mxArray. There are a number of
functions to create mxArray structures, including
mxCreateDoubleMatrix, mxCreateCellArray, mxCreateSparse,
and the generic mxCreateNumericArray.
The basic function to access the data contained in an array is
mxGetPr. As the mex interface assumes that real and imaginary
parts of a complex array are stored separately, there is an equivalent
function mxGetPi that gets the imaginary part. Both of these
functions are only for use with double precision matrices. The generic
functions mxGetData and mxGetImagData perform the same operation
on all matrix types. For example:
mxArray *m; mwSize *dims; UINT32_T *pr; dims = (mwSize *) mxMalloc (2 * sizeof (mwSize)); dims[0] = 2; dims[1] = 2; m = mxCreateNumericArray (2, dims, mxUINT32_CLASS, mxREAL); pr = (UINT32_T *) mxGetData (m);
There are also the functions mxSetPr, etc., that perform the
inverse, and set the data of an array to use the block of memory pointed
to by the argument of mxSetPr.
Note the type mwSize used above, and also mwIndex, are defined
as the native precision of the indexing in Octave on the platform on
which the mex-file is built. This allows both 32- and 64-bit platforms
to support mex-files. mwSize is used to define array dimensions
and the maximum number or elements, while mwIndex is used to define
indexing into arrays.
An example that demonstrates how to work with arbitrary real or complex double precision arrays is given by the file mypow2.c shown below.
#include "mex.h"
void
mexFunction (int nlhs, mxArray* plhs[],
int nrhs, const mxArray* prhs[])
{
mwSize n;
mwIndex i;
double *vri, *vro;
if (nrhs != 1 || ! mxIsNumeric (prhs[0]))
mexErrMsgTxt ("ARG1 must be a matrix");
n = mxGetNumberOfElements (prhs[0]);
plhs[0] = mxCreateNumericArray (mxGetNumberOfDimensions (prhs[0]),
mxGetDimensions (prhs[0]),
mxGetClassID (prhs[0]),
mxIsComplex (prhs[0]));
vri = mxGetPr (prhs[0]);
vro = mxGetPr (plhs[0]);
if (mxIsComplex (prhs[0]))
{
double *vii, *vio;
vii = mxGetPi (prhs[0]);
vio = mxGetPi (plhs[0]);
for (i = 0; i < n; i++)
{
vro[i] = vri[i] * vri[i] - vii[i] * vii[i];
vio[i] = 2 * vri[i] * vii[i];
}
}
else
{
for (i = 0; i < n; i++)
vro[i] = vri[i] * vri[i];
}
}
with an example of its use
b = randn (4,1) + 1i * randn (4,1); all (b.^2 == mypow2 (b)) ⇒ 1
The example above uses the functions mxGetDimensions,
mxGetNumberOfElements, and mxGetNumberOfDimensions to work
with the dimensions of multi-dimensional arrays. The functions
mxGetM, and mxGetN are also available to find the number
of rows and columns in a 2-D matrix.
Next: Character Strings in Mex-Files, Previous: Getting Started with Mex-Files, Up: Mex-Files [Contents][Index]