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 VlArray *	vlmxEnvelopeArrayInVlArray (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 VlEnumerator *	vlmxDecodeEnumeration (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.

Plain scalar, vector, and matrix are a scalar, vector, and matrix arrays which are real and of class mxDOUBLE_CLASS. Use vlmxIsPlainScalar, vlmxIsPlainVector and vlmxIsPlainMatrix to check this.

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:

s1	first string.
s2	second 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:

array	first string (as a MATLAB array).
string	second 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:

x	VlArray instance.

Returns:: the new array.

static mxArray* vlmxCreatePlainScalar ( double x )

static

Parameters:

x	scalar value.

Returns:: the new array.

static VlEnumerator* vlmxDecodeEnumeration	(	mxArray const *	name_array,
		VlEnumerator const *	enumeration,
		vl_bool	caseInsensitive
	)

static

Parameters:

enumeration	the enumeration to decode.
name_array	member name as a MATLAB string array.
caseInsensitive	if `true` match the string case-insensitive.

Returns:: the corresponding enumeration member, or NULL if any.

static VlArray* vlmxEnvelopeArrayInVlArray	(	VlArray *	v,
		mxArray *	x
	)

static

Parameters:

v	VlArray instance (out)
x	MATALB array.

Returns:: v.

static void vlmxError	(	VlmxErrorId	errorId,
		char const *	errorMessage,
			...
	)

static

Parameters:

errorId	error ID string.
errorMessage	error 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:

array	array to check.
numDimensions	number of dimensions.
dimensions	dimensions.

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:

array	first string (as a MATLAB array).
string	second string.

Returns:: true if the strings are equal.

static vl_bool vlmxIsMatrix	(	mxArray const *	array,
		vl_index	M,
		vl_index	N
	)

static

Parameters:

array	MATLAB array.
M	number of rows (negative for any).
N	number 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:

array	MATLAB array.
classId	prescribed 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:

array MATLAB 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:

array	MATLAB array.
M	number of rows (negative for any).
N	number 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:

array MATLAB 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:

array	MATLAB array.
numElements	number 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:

array MATLAB array.

Returns:: VL_TRUE if the array is real.

See also:: Array tests

vl_bool vlmxIsScalar ( mxArray const * array )

inline

Parameters:

array MATLAB array.

Returns:: VL_TRUE if the array is scalar.

See also:: Array tests

static int vlmxIsString	(	const mxArray *	array,
		vl_index	length
	)

static

Parameters:

array	array to test.
length	string 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:

array	MATLAB array.
numElements	number 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:

args	MEX argument array.
nargs	MEX argument array length.
options	List of option definitions.
next	Pointer to the next option (input and output).
optarg	Pointer 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:

errorId	error ID string.
errorMessage	error message C-style format string.
...	format string arguments.

The function internally calls mxWarnMsgTxtAndId.

VLFeat.org

Data Structures

Macros

Functions

Error handling

Detailed Description

VLFeat environment

Array tests

Parsing options

Macro Definition Documentation

Function Documentation