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. mxArray
serves essentially the same purpose as the octave_value
class in
oct-files in that it acts as a container for all 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 in an array is mxGetPr
. Because
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 for 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 || ! mxIsDouble (prhs[0])) mexErrMsgTxt ("ARG1 must be a double 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]; } }
An example of its use is
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 (MxN matrix).
Next: Character Strings in Mex-Files, Previous: Getting Started with Mex-Files, Up: Mex-Files [Contents][Index]