Documentation - C API
mexutils.h File Reference

MEX utilities. More...

#include "mex.h"
#include <vl/generic.h>
#include <vl/array.h>
#include <vl/stringop.h>
#include <ctype.h>
#include <string.h>
#include <stdio.h>
#include <stdarg.h>

Data Structures

struct  vlmxOption
 MEX option. More...

Macros

#define IN(x)   (in[IN_ ## x])
 Access MEX input argument.
#define OUT(x)   (out[OUT_ ## x])
 Access MEX output argument.
#define VL_USE_MATLAB_ENV
 Setup VLFeat to be used in a MEX file.

Functions

static mxArray * vlmxCreatePlainScalar (double x)
 Create a MATLAB array which is a plain scalar.
static mxArray * vlmxCreateArrayFromVlArray (VlArray const *x)
 Create a MATLAB array from a VlArray.
static VlArrayvlmxEnvelopeArrayInVlArray (VlArray *v, mxArray *x)
 Envelope a MATLAB array in a VlArray instance.
static int vlmxCompareStringsI (const char *s1, const char *s2)
 Case insensitive string comparison.
static int vlmxCompareToStringI (mxArray const *array, char const *string)
 Case insensitive string comparison with array.
static int vlmxIsEqualToStringI (mxArray const *array, char const *string)
 Case insensitive string equality test with array.
static int vlmxNextOption (mxArray const *args[], int nargs, vlmxOption const *options, int *next, mxArray const **optarg)
 Parse the next option.
static VlEnumeratorvlmxDecodeEnumeration (mxArray const *name_array, VlEnumerator const *enumeration, vl_bool caseInsensitive)
 Get an emumeration member by name.
Check for array attributes
vl_bool vlmxIsOfClass (mxArray const *array, mxClassID classId)
 Check if a MATLAB array is of a prescribed class.
vl_bool vlmxIsReal (mxArray const *array)
 Check if a MATLAB array is real.
Check for scalar, vector and matrix arrays
vl_bool vlmxIsScalar (mxArray const *array)
 Check if a MATLAB array is scalar.
static vl_bool vlmxIsVector (mxArray const *array, vl_index numElements)
 Check if a MATLAB array is a vector.
static vl_bool vlmxIsMatrix (mxArray const *array, vl_index M, vl_index N)
 Check if a MATLAB array is a matrix.
static vl_bool vlmxIsArray (mxArray const *array, vl_index numDimensions, vl_index *dimensions)
 Check if the MATLAB array has the specified dimensions.
Check for plain arrays
vl_bool vlmxIsPlain (mxArray const *array)
 Check if a MATLAB array is plain.
vl_bool vlmxIsPlainScalar (mxArray const *array)
 Check if a MATLAB array is plain scalar.
vl_bool vlmxIsPlainVector (mxArray const *array, vl_index numElements)
 Check if a MATLAB array is a plain vector.
vl_bool vlmxIsPlainMatrix (mxArray const *array, vl_index M, vl_index N)
 Check if a MATLAB array is a plain matrix.
static int vlmxIsString (const mxArray *array, vl_index length)
 Check if the array is a string.

Error handling

enum  VlmxErrorId
 VLFeat MEX errors.
static void vlmxError (VlmxErrorId errorId, char const *errorMessage,...)
 Raise a MEX error with VLFeat format.
static void vlmxWarning (VlmxErrorId errorId, char const *errorMessage,...)
 Raise a MEX warning with VLFeat format.

Detailed Description

Author:
Andrea Vedaldi

This header file provides helper functions for writing MATLAB MEX files.

VLFeat environment

When the VLFeat DLL is linked to a MATLAB MEX files, at run time the MEX file must configure VLFeat to use MATLAB memory allocation and logging functions. This can be obtained by calling the macro VL_USE_MATLAB_ENV as the first line of each MEX file which is linked to the VLFeat DLL.

Array tests

MATLAB supports a variety of array types. Most MEX file arguments are restricted to a few types and must be properly checked at run time. mexutils.h provides some helper functions to make it simpler to check such arguments. MATLAB basic array types are:

  • Numeric array: mxDOUBLE_CLASS, mxSINGLE_CLASS, mxINT8_CLASS, mxUINT8_CLASS, mxINT16_CLASS, mxUINT16_CLASS, mxINT32_CLASS, mxUINT32_CLASS. Moreover:
    • all such types have a real component
    • all such types may have a imaginary component
    • mxDOUBLE_LCASS arrays with two dimensions can be sparse.
  • Logical array (mxLOGICAL_CLASS).
  • Character array (mxCHAR_CLASS).

The other MATLAB array types are:

  • Struct array (mxSTRUCT_CLASS).
  • Cell array (mxCELL_CLASS).
  • Custom class array (mxCLASS_CLASS).
  • Unkown type array (mxUNKNOWN_CLASS).

VLFeat defines a number of common classes of arrays and corresponding tests.

  • Scalar array is a non-sparse array with exactly one element. Note that the array may have an arbitrary number of dimensions, and be of any numeric or other type. All dimensions are singleton (which is implied by having exactly one element). Use vlmxIsScalar to test if an array is scalar.
  • Vector array is a non-sparse array which is either empty (empty vector) or has at most one non-singleton dimension. The array can be of any numeric or other type. The elements of such a MATLAB array are stored as a plain C array with a number of elements equal to the number of elements in the array (obtained with mxGetNumberOfElements). Use vlmxIsVector to test whether an array is a vector.
  • Matrix array is a non-sparse array for which all dimensions beyond the first two are singleton, or a non-sparse array which is empty and for which at least one of the first two dimensions is zero. The array can be of any numeric or other type. The non-singleton dimensions can be zero (empty matrix), one, or more. The element of such a MATLAB array are stored as a C array in column major order and its dimensions can be obtained by mxGetM and mxGetN. Use vlmxIsMatrix to test if an array is a matrix.
  • Real array is a numeric array (as for mxIsNumeric) without a complex component. Use vlmxIsReal to check if an array is real.
  • Use vlmxIsOfClass to check if an array is of a prescribed (storage) class, such as mxDOUBLE_CLASS.

Parsing options

It is common to pass optional arguments to a MEX file as option type-value pairs. Here type is a string identifying the option and value is a MATLAB array specifing its value. The function vlmxNextOption can be used to simplify parsing a list of such arguments (similar to UNIX getopt). The functions vlmxError and vlmxWarning are shortcuts to specify VLFeat formatted errors.


Macro Definition Documentation

#define VL_USE_MATLAB_ENV
Value:
vl_set_alloc_func (mxMalloc, mxRealloc, mxCalloc, mxFree) ; \
vl_set_printf_func ((printf_func_t)mexPrintf) ;

This makes VLFeat use MATLAB version of the memory allocation and logging functions.


Function Documentation

static int vlmxCompareStringsI ( const char *  s1,
const char *  s2 
)
static
Parameters:
s1first string.
s2second string.
Returns:
comparison result.

The comparison result is equal to 0 if the strings are equal, >0 if the first string is greater than the second (in lexicographical order), and <0 otherwise.

static int vlmxCompareToStringI ( mxArray const *  array,
char const *  string 
)
static
Parameters:
arrayfirst string (as a MATLAB array).
stringsecond string.
Returns:
comparison result.

The comparison result is equal to 0 if the strings are equal, >0 if the first string is greater than the second (in lexicographical order), and <0 otherwise.

static mxArray* vlmxCreateArrayFromVlArray ( VlArray const *  x)
static
Parameters:
xVlArray instance.
Returns:
the new array.
static mxArray* vlmxCreatePlainScalar ( double  x)
static
Parameters:
xscalar value.
Returns:
the new array.
static VlEnumerator* vlmxDecodeEnumeration ( mxArray const *  name_array,
VlEnumerator const *  enumeration,
vl_bool  caseInsensitive 
)
static
Parameters:
enumerationthe enumeration to decode.
name_arraymember name as a MATLAB string array.
caseInsensitiveif true match the string case-insensitive.
Returns:
the corresponding enumeration member, or NULL if any.
static VlArray* vlmxEnvelopeArrayInVlArray ( VlArray v,
mxArray *  x 
)
static
Parameters:
vVlArray instance (out)
xMATALB array.
Returns:
v.
static void vlmxError ( VlmxErrorId  errorId,
char const *  errorMessage,
  ... 
)
static
Parameters:
errorIderror ID string.
errorMessageerror message C-style format string.
...format string arguments.

The function internally calls mxErrMsgTxtAndId, which causes the MEX file to abort.

static vl_bool vlmxIsArray ( mxArray const *  array,
vl_index  numDimensions,
vl_index dimensions 
)
static
Parameters:
arrayarray to check.
numDimensionsnumber of dimensions.
dimensionsdimensions.
Returns:
true the test succeeds.

The test is true if numDimensions < 0. If not, it is false if the array has not numDimensions. Otherwise it is true is dimensions is NULL or if each entry of dimensions is either negative or equal to the corresponding array dimension.

static int vlmxIsEqualToStringI ( mxArray const *  array,
char const *  string 
)
static
Parameters:
arrayfirst string (as a MATLAB array).
stringsecond string.
Returns:
true if the strings are equal.
static vl_bool vlmxIsMatrix ( mxArray const *  array,
vl_index  M,
vl_index  N 
)
static
Parameters:
arrayMATLAB array.
Mnumber of rows (negative for any).
Nnumber of columns (negative for any).
Returns:
VL_TRUE if the array is a matrix of the prescribed size.
See also:
Array tests
vl_bool vlmxIsOfClass ( mxArray const *  array,
mxClassID  classId 
)
inline
Parameters:
arrayMATLAB array.
classIdprescribed class of the array.
Returns:
VL_TRUE if the class is of the array is of the prescribed class.
See also:
Array tests
vl_bool vlmxIsPlain ( mxArray const *  array)
inline
Parameters:
arrayMATLAB array.
Returns:
VL_TRUE if the array is plain.
See also:
Array tests
vl_bool vlmxIsPlainMatrix ( mxArray const *  array,
vl_index  M,
vl_index  N 
)
inline
Parameters:
arrayMATLAB array.
Mnumber of rows (negative for any).
Nnumber of columns (negative for any).
Returns:
VL_TRUE if the array is a plain matrix of the prescribed size.
See also:
Array tests
vl_bool vlmxIsPlainScalar ( mxArray const *  array)
inline
Parameters:
arrayMATLAB array.
Returns:
VL_TRUE if the array is plain scalar.
See also:
Array tests
vl_bool vlmxIsPlainVector ( mxArray const *  array,
vl_index  numElements 
)
inline
Parameters:
arrayMATLAB array.
numElementsnumber of elements (negative for any).
Returns:
VL_TRUE if the array is a plain vecotr of the prescribed size.
See also:
Array tests
vl_bool vlmxIsReal ( mxArray const *  array)
inline
Parameters:
arrayMATLAB array.
Returns:
VL_TRUE if the array is real.
See also:
Array tests
vl_bool vlmxIsScalar ( mxArray const *  array)
inline
Parameters:
arrayMATLAB array.
Returns:
VL_TRUE if the array is scalar.
See also:
Array tests
static int vlmxIsString ( const mxArray *  array,
vl_index  length 
)
static
Parameters:
arrayarray to test.
lengthstring length.
Returns:
true if the array is a string of the specified length

The array array satisfies the test if:

  • its storage class is CHAR;
  • it has two dimensions but only one row;
  • length < 0 or the array has length columns.
static vl_bool vlmxIsVector ( mxArray const *  array,
vl_index  numElements 
)
static
Parameters:
arrayMATLAB array.
numElementsnumber of elements (negative for any).
Returns:
VL_TRUE if the array is a vecotr of the prescribed size.
See also:
Array tests
static int vlmxNextOption ( mxArray const *  args[],
int  nargs,
vlmxOption const *  options,
int *  next,
mxArray const **  optarg 
)
static
Parameters:
argsMEX argument array.
nargsMEX argument array length.
optionsList of option definitions.
nextPointer to the next option (input and output).
optargPointer to the option optional argument (output).
Returns:
the code of the next option, or -1 if there are no more options.

The function parses the array args for options. args is expected to be a sequence alternating option names and option values, in the form of nargs instances of mxArray. The function then scans the option starting at position next in the array. The option name is matched (case insensitive) to the table of options options, a pointer to the option value is stored in optarg, next is advanced to the next option, and the option code is returned.

The function is typically used in a loop to parse all the available options. next is initialized to zero, and then the function is called until the special code -1 is returned.

If the option name cannot be matched to the available options, either because the option name is not a string array or because the name is unknown, the function exits the MEX file with an error.

static void vlmxWarning ( VlmxErrorId  errorId,
char const *  errorMessage,
  ... 
)
static
Parameters:
errorIderror ID string.
errorMessageerror message C-style format string.
...format string arguments.

The function internally calls mxWarnMsgTxtAndId.