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.