Documentation>C API
Data Structures | Macros | Functions
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)
| Access MEX input argument.
#define | 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
- Array tests
- Parsing options

# 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

## ◆ VL_USE_MATLAB_ENV

#define VL_USE_MATLAB_ENV

Value:
vl_set_alloc_func (mxMalloc, mxRealloc, mxCalloc, mxFree) ; \
vl_set_printf_func ((printf_func_t)mexPrintf) ;
vl_set_alloc_func
void vl_set_alloc_func(void *(*malloc_func)(size_t), void *(*realloc_func)(void *, size_t), void *(*calloc_func)(size_t, size_t), void(*free_func)(void *))
Set memory allocation functions.
Definition generic.c:1288
printf_func_t
int(* printf_func_t)(char const *format,...)
Customizable printf function pointer type.
Definition generic.h:154

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

## Function Documentation

## ◆ vlmxCompareStringsI()

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.

## ◆ vlmxCompareToStringI()

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.

## ◆ vlmxCreateArrayFromVlArray()

mxArray * vlmxCreateArrayFromVlArray | ( | VlArray const * | x | ) |

static

Parameters

  x | VlArray instance.

Returns
  the new array.

## ◆ vlmxCreatePlainScalar()

mxArray * vlmxCreatePlainScalar | ( | double | x | ) |

static

Parameters

  x | scalar value.

Returns
  the new array.

## ◆ vlmxDecodeEnumeration()

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.

## ◆ vlmxEnvelopeArrayInVlArray()

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

static

Parameters

  v | VlArray instance (out)
  x | MATALB array.

Returns
  `v`.

## ◆ vlmxError()

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.

## ◆ vlmxIsArray()

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.

## ◆ vlmxIsEqualToStringI()

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.

## ◆ vlmxIsMatrix()

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

## ◆ vlmxIsOfClass()

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

## ◆ vlmxIsPlain()

vl_bool vlmxIsPlain | ( | mxArray const * | array | ) |

inline

Parameters

  array | MATLAB array.

Returns
  VL_TRUE if the array is plain.

See also
  Array tests

## ◆ vlmxIsPlainMatrix()

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

## ◆ vlmxIsPlainScalar()

vl_bool vlmxIsPlainScalar | ( | mxArray const * | array | ) |

inline

Parameters

  array | MATLAB array.

Returns
  VL_TRUE if the array is plain scalar.

See also
  Array tests

## ◆ vlmxIsPlainVector()

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

## ◆ vlmxIsReal()

vl_bool vlmxIsReal | ( | mxArray const * | array | ) |

inline

Parameters

  array | MATLAB array.

Returns
  VL_TRUE if the array is real.

See also
  Array tests

## ◆ vlmxIsScalar()

vl_bool vlmxIsScalar | ( | mxArray const * | array | ) |

inline

Parameters

  array | MATLAB array.

Returns
  VL_TRUE if the array is scalar.

See also
  Array tests

## ◆ vlmxIsString()

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.

## ◆ vlmxIsVector()

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

## ◆ vlmxNextOption()

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.

## ◆ vlmxWarning()

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`.