mexPackage

Seamless integration of C/C++ into Matlab

Overview:

The mexPackage library provides a framework for exposing C++ types and functions directly into Matlab, easily and seamlessly, such that they behave like native Matlab classes and functions. C++ types can be mapped automatically to either a Matlab built-in type, or a custom Matlab class. Fundamental types like int, double, and STL classes like std::complex, std::vector, etc. are all natively supported with conversions to an equivalent Matlab built-in type. One can also choose to expose a C++ type as a custom Matlab class to provide access to almost all its attributes, including:

•constructors

•base classes

•data members

•methods

•static members and methods

•type members

mexPackage is designed to be an extensible library. The user can add support for his/her own C++ types. C++ traits classes are used to define the mapping to Matlab built-in types. For mapping to a custom Matlab class, a class interface description is needed, called a mexClass definition, which is specially written C++ code based on a particular format specification. No modification of the existing C++ code is needed. The additional C++ code that is needed to define how to expose the user’s various C++ types and functions, can either be embedded alongside the existing code, or included from separate header files, which are compiled along with the mexPackage library to generate a standard mex library. mexPackage provides a collection of Matlab .m files which are used to load and use this mex library.

In Matlab, the C++ classes and functions appear and behave like native Matlab classes and functions. C++ classes can be instantiated to create C++ objects in Matlab, allowing access to its properties and methods. C++ functions can be like any other Matlab function, and type conversions of the input and output arguments are handled automatically.

Instructions:

Place all C++ source files in a separate directory that is in the include path of the mex compile. Include mex_package_ALL.cpp in the mex compile. Place all Matlab *.m files in a directory that is in the Matlab startup path. Detailed documentation on this library can be found in mexPackage.pdf.

Brief excerpt of the tutorial in mexPackage.pdf:

Let’s start with the following classic function.

const char* greet() {

return “hello, world”;

};

To expose this function in Matlab, we define our mex package to include this function as follows.

#include “mex_package.h”

MEX_PACKAGE {

function_(“greet”, greet);

}

After compiling your code into a mex library, let’s say called mex_hello.mexa64, we can use our function in this sample Matlab session.

>> hello = mexPackage(@mex_hello);

>> hello.greet()

ans =

hello, world

4.2ssCLASS METHODS

Now, consider the follow C++ class to be exposed to Matlab.

struct World {

void set(std::string msg) { this->msg = msg; }

std::string greet() { return msg; }

std::string msg;

};

Unlike functions, adding a C++ class to a mex package also requires a description of the class to be defined, called a mexClass definition. For our example class, we can specify that we want to expose the methods of this class with the following.

#include “mex_class.h”

MEX_CLASS(World) {

def(self)

.mex_method(set)

.mex_method(greet)

;

}

Now we can add our class to our mex package example.

#include “mex_package.h”

MEX_PACKAGE {

function_(“greet”, greet);

class_<World>(“World”);

)

You can use your class, World, in a Matlab session like this.

>> hello = mexPackage(@mex_hello);

>> planet = hello.World();

Creating mexClass object 0: @mex_hello::World

>> planet.set('howdy');

>> planet.greet()

ans =

howdy

4.3ssCONSTRUCTORS

The previous example class didn’t have any explicit constructors, but it does have an implicit default constructor which is automatically exposed, and that is what was used in the previous example. You may add a non-default constructor by building on the previous example like this:

struct World {

World(std::string msg) : msg(msg) {} // added constructor

void set(std::string msg) { this->msg = msg; }

std::string greet() { return msg; }

std::string msg;

};

Because the class World no longer has a default constructor, the previous mexClass class definition would not compile unless we update it like this:

#include “mex_class.h”

MEX_CLASS(World) {

def(self)

.ctor<std::string>()

.mex_method(set)

.mex_method(greet)

;

}

The ctor() function specifies the argument format of the constructor for the class World. If you do not intend to directly instantiate your class in Matlab, then you do not need to use ctor(), even if your class does not have a default constructor. You can now use your newly defined constructor in this updated example Matlab session.

>> hello = mexPackage(@mex_hello);

>> planet = hello.World(‘howdy’);

Creating mexClass object 0: @mex_hello::World

>> planet.greet()

ans =

howdy