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>
Go to the source code of this file.
Classes | |
struct | _vlmxOption |
MEX option. More... | |
Defines | |
#define | IN(x) (in[IN_ ## x]) |
Access MEX input argument. | |
#define | MEXUTILS_RAISE_HELPER MEXUTILS_RAISE_HELPER_A MEXUTILS_RAISE_HELPER_B |
#define | MEXUTILS_RAISE_HELPER_A |
#define | MEXUTILS_RAISE_HELPER_B |
#define | OUT(x) (out[OUT_ ## x]) |
Access MEX output argument. | |
#define | VL_USE_MATLAB_ENV |
Setup VLFeat to be used in a MEX file. | |
Typedefs | |
typedef vl_int32 | mwIndex |
typedef vl_uint32 | mwSize |
typedef struct _vlmxOption | vlmxOption |
MEX option type. | |
Functions | |
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 mxArray * | vlmxCreateArrayFromVlArray (VlArray const *x) |
Create a MATLAB array from a VlArray. | |
static mxArray * | vlmxCreatePlainScalar (double x) |
Create a MATLAB array which is a plain scalar. | |
static VlEnumerator * | vlmxDecodeEnumeration (mxArray const *name_array, VlEnumerator const *enumeration, vl_bool caseInsensitive) |
Get an emumeration member by name. | |
static VlArray * | vlmxEnvelopeArrayInVlArray (VlArray *v, mxArray *x) |
Envelope a MATLAB array in a VlArray instance. | |
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. | |
Check for array attributes | |
VL_INLINE vl_bool | vlmxIsOfClass (mxArray const *array, mxClassID classId) |
Check if a MATLAB array is of a prescribed class. | |
VL_INLINE vl_bool | vlmxIsReal (mxArray const *array) |
Check if a MATLAB array is real. | |
Check for scalar, vector and matrix arrays | |
VL_INLINE 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_INLINE vl_bool | vlmxIsPlain (mxArray const *array) |
Check if a MATLAB array is plain. | |
VL_INLINE vl_bool | vlmxIsPlainScalar (mxArray const *array) |
Check if a MATLAB array is plain scalar. | |
VL_INLINE vl_bool | vlmxIsPlainVector (mxArray const *array, vl_index numElements) |
Check if a MATLAB array is a plain vector. | |
VL_INLINE 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 { vlmxErrAlloc = 1, vlmxErrInvalidArgument, vlmxErrNotEnoughInputArguments, vlmxErrTooManyInputArguments, vlmxErrNotEnoughOutputArguments, vlmxErrTooManyOutputArguments, vlmxErrInvalidOption, vlmxErrInconsistentData } |
VLFeat MEX errors. More... | |
typedef enum _VlmxErrorId | 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. |
MEX utilities.
This header file provides helper functions for writing MATLAB MEX files.
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.
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:
mxDOUBLE_CLASS
, mxSINGLE_CLASS
, mxINT8_CLASS
, mxUINT8_CLASS
, mxINT16_CLASS
, mxUINT16_CLASS
, mxINT32_CLASS
, mxUINT32_CLASS
. Moreover:mxDOUBLE_LCASS
arrays with two dimensions can be sparse.mxLOGICAL_CLASS
).mxCHAR_CLASS
).The other MATLAB array types are:
mxSTRUCT_CLASS
).mxCELL_CLASS
).mxCLASS_CLASS
).mxUNKNOWN_CLASS
).VLFeat defines a number of common classes of arrays and corresponding tests.
mxGetNumberOfElements
). Use vlmxIsVector to test whether an array is a vector.mxGetM
and mxGetN
. Use vlmxIsMatrix to test if an array is a matrix.mxIsNumeric
) without a complex component. Use vlmxIsReal to check if an array is real.mxDOUBLE_CLASS
.mxDOUBLE_CLASS
. Use vlmxIsPlainScalar, vlmxIsPlainVector and vlmxIsPlainMatrix to check this.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.
Definition in file mexutils.h.
#define IN | ( | x | ) | (in[IN_ ## x]) |
Access MEX input argument.
Definition at line 39 of file mexutils.h.
Definition at line 240 of file mexutils.h.
#define MEXUTILS_RAISE_HELPER_A |
char const * errorString ; \ char formattedErrorId [512] ; \ char formattedErrorMessage [1024] ; \ \ switch (errorId) { \ case vlmxErrAlloc : errorString = "outOfMemory" ; break ; \ case vlmxErrInvalidArgument : errorString = "invalidArgument" ; break ; \ case vlmxErrNotEnoughInputArguments : errorString = "notEnoughInputArguments" ; break ; \ case vlmxErrTooManyInputArguments : errorString = "tooManyInputArguments" ; break ; \ case vlmxErrNotEnoughOutputArguments : errorString = "notEnoughOutputArguments" ; break ; \ case vlmxErrTooManyOutputArguments : errorString = "tooManyOutputArguments" ; break ; \ case vlmxErrInvalidOption : errorString = "invalidOption" ; break ; \ case vlmxErrInconsistentData : errorString = "inconsistentData" ; break ; \ default : errorString = "undefinedError" ; break ; \ } \ \ if (! errorMessage) { \ switch (errorId) { \ case vlmxErrAlloc: errorMessage = "Out of memory." ; break ; \ case vlmxErrInvalidArgument: errorMessage = "Invalid argument." ; break ; \ case vlmxErrNotEnoughInputArguments: errorMessage = "Not enough input arguments." ; break ; \ case vlmxErrTooManyInputArguments: errorMessage = "Too many input arguments." ; break ; \ case vlmxErrNotEnoughOutputArguments: errorMessage = "Not enough output arguments." ; break ; \ case vlmxErrTooManyOutputArguments: errorMessage = "Too many output arguments." ; break ; \ case vlmxErrInconsistentData: errorMessage = "Inconsistent data." ; break ; \ case vlmxErrInvalidOption: errorMessage = "Invalid option." ; break ; \ default: errorMessage = "Undefined error message." ; \ } \ }
Definition at line 183 of file mexutils.h.
#define MEXUTILS_RAISE_HELPER_B |
{ \ va_list args ; \ va_start(args, errorMessage) ; \ snprintf(formattedErrorId, \ sizeof(formattedErrorId)/sizeof(char), \ "vl:%s", errorString) ; \ vsnprintf(formattedErrorMessage, \ sizeof(formattedErrorMessage)/sizeof(char), \ errorMessage, args) ; \ va_end(args) ; \ }
Definition at line 226 of file mexutils.h.
#define OUT | ( | x | ) | (out[OUT_ ## x]) |
Access MEX output argument.
Definition at line 43 of file mexutils.h.
#define VL_USE_MATLAB_ENV |
vl_set_alloc_func (mxMalloc, mxRealloc, mxCalloc, mxFree) ; \ vl_set_printf_func ((printf_func_t)mexPrintf) ;
Setup VLFeat to be used in a MEX file.
This makes VLFeat use MATLAB version of the memory allocation and logging functions.
Definition at line 76 of file mexutils.h.
Definition at line 34 of file mexutils.h.
Definition at line 33 of file mexutils.h.
typedef enum _VlmxErrorId VlmxErrorId |
VLFeat MEX errors.
typedef struct _vlmxOption vlmxOption |
MEX option type.
Definition at line 734 of file mexutils.h.
enum _VlmxErrorId |
VLFeat MEX errors.
Definition at line 247 of file mexutils.h.
static int vlmxCompareStringsI | ( | const char * | s1, |
const char * | s2 | ||
) | [static] |
Case insensitive string comparison.
------------------------------------------------------------------
s1 | first string. |
s2 | second string. |
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.
Definition at line 660 of file mexutils.h.
static int vlmxCompareToStringI | ( | mxArray const * | array, |
char const * | string | ||
) | [static] |
Case insensitive string comparison with array.
------------------------------------------------------------------
array | first string (as a MATLAB array). |
string | second string. |
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.
Definition at line 687 of file mexutils.h.
static mxArray* vlmxCreateArrayFromVlArray | ( | VlArray const * | x | ) | [static] |
Create a MATLAB array from a VlArray.
------------------------------------------------------------------
x | VlArray instance. |
Definition at line 567 of file mexutils.h.
static mxArray* vlmxCreatePlainScalar | ( | double | x | ) | [static] |
Create a MATLAB array which is a plain scalar.
------------------------------------------------------------------
x | scalar value. |
Definition at line 553 of file mexutils.h.
static VlEnumerator* vlmxDecodeEnumeration | ( | mxArray const * | name_array, |
VlEnumerator const * | enumeration, | ||
vl_bool | caseInsensitive | ||
) | [static] |
Get an emumeration member by name.
enumeration | the enumeration to decode. |
name_array | member name as a MATLAB string array. |
caseInsensitive | if true match the string case-insensitive. |
NULL
if any. Definition at line 832 of file mexutils.h.
static VlArray* vlmxEnvelopeArrayInVlArray | ( | VlArray * | v, |
mxArray * | x | ||
) | [static] |
Envelope a MATLAB array in a VlArray instance.
------------------------------------------------------------------
v | VlArray instance (out) |
x | MATALB array. |
v
. Definition at line 617 of file mexutils.h.
static void vlmxError | ( | VlmxErrorId | errorId, |
char const * | errorMessage, | ||
... | |||
) | [static] |
Raise a MEX error with VLFeat format.
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.
Definition at line 273 of file mexutils.h.
static vl_bool vlmxIsArray | ( | mxArray const * | array, |
vl_index | numDimensions, | ||
vl_index * | dimensions | ||
) | [static] |
Check if the MATLAB array has the specified dimensions.
------------------------------------------------------------------
array | array to check. |
numDimensions | number of dimensions. |
dimensions | dimensions. |
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.
Definition at line 434 of file mexutils.h.
static int vlmxIsEqualToStringI | ( | mxArray const * | array, |
char const * | string | ||
) | [static] |
Case insensitive string equality test with array.
------------------------------------------------------------------
array | first string (as a MATLAB array). |
string | second string. |
Definition at line 714 of file mexutils.h.
static vl_bool vlmxIsMatrix | ( | mxArray const * | array, |
vl_index | M, | ||
vl_index | N | ||
) | [static] |
Check if a MATLAB array is a matrix.
------------------------------------------------------------------
array | MATLAB array. |
M | number of rows (negative for any). |
N | number of columns (negative for any). |
Definition at line 390 of file mexutils.h.
VL_INLINE vl_bool vlmxIsOfClass | ( | mxArray const * | array, |
mxClassID | classId | ||
) |
Check if a MATLAB array is of a prescribed class.
------------------------------------------------------------------
array | MATLAB array. |
classId | prescribed class of the array. |
Definition at line 308 of file mexutils.h.
VL_INLINE vl_bool vlmxIsPlain | ( | mxArray const * | array | ) |
Check if a MATLAB array is plain.
------------------------------------------------------------------
array | MATLAB array. |
Definition at line 467 of file mexutils.h.
VL_INLINE vl_bool vlmxIsPlainMatrix | ( | mxArray const * | array, |
vl_index | M, | ||
vl_index | N | ||
) |
Check if a MATLAB array is a plain matrix.
------------------------------------------------------------------
array | MATLAB array. |
M | number of rows (negative for any). |
N | number of columns (negative for any). |
Definition at line 513 of file mexutils.h.
VL_INLINE vl_bool vlmxIsPlainScalar | ( | mxArray const * | array | ) |
Check if a MATLAB array is plain scalar.
------------------------------------------------------------------
array | MATLAB array. |
Definition at line 483 of file mexutils.h.
VL_INLINE vl_bool vlmxIsPlainVector | ( | mxArray const * | array, |
vl_index | numElements | ||
) |
Check if a MATLAB array is a plain vector.
------------------------------------------------------------------
array | MATLAB array. |
numElements | number of elements (negative for any). |
Definition at line 497 of file mexutils.h.
VL_INLINE vl_bool vlmxIsReal | ( | mxArray const * | array | ) |
Check if a MATLAB array is real.
------------------------------------------------------------------
array | MATLAB array. |
Definition at line 321 of file mexutils.h.
VL_INLINE vl_bool vlmxIsScalar | ( | mxArray const * | array | ) |
Check if a MATLAB array is scalar.
------------------------------------------------------------------
array | MATLAB array. |
Definition at line 339 of file mexutils.h.
static int vlmxIsString | ( | const mxArray * | array, |
vl_index | length | ||
) | [static] |
Check if the array is a string.
------------------------------------------------------------------
array | array to test. |
length | string length. |
The array array satisfies the test if:
Definition at line 531 of file mexutils.h.
static vl_bool vlmxIsVector | ( | mxArray const * | array, |
vl_index | numElements | ||
) | [static] |
Check if a MATLAB array is a vector.
------------------------------------------------------------------
array | MATLAB array. |
numElements | number of elements (negative for any). |
Definition at line 353 of file mexutils.h.
static int vlmxNextOption | ( | mxArray const * | args[], |
int | nargs, | ||
vlmxOption const * | options, | ||
int * | next, | ||
mxArray const ** | optarg | ||
) | [static] |
Parse the next option.
------------------------------------------------------------------
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). |
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.
Definition at line 765 of file mexutils.h.
static void vlmxWarning | ( | VlmxErrorId | errorId, |
char const * | errorMessage, | ||
... | |||
) | [static] |
Raise a MEX warning with VLFeat format.
errorId | error ID string. |
errorMessage | error message C-style format string. |
... | format string arguments. |
The function internally calls mxWarnMsgTxtAndId
.
Definition at line 288 of file mexutils.h.