Main Content

Define MATLAB Interface for C++ Library

How to Complete Definitions in Library Definition File

The MATLAB® interface converts C++ function signatures into MATLAB function signatures. Some C++ language constructs do not have unique matches in the MATLAB language. MATLAB uses a library definition file (with the M file extension), which a publisher creates and modifies to provide missing information. The publisher must have enough C++ language skills to interpret a function signature and provide the missing information.

MATLAB informs you about these incomplete definitions through this clibgen.generateLibraryDefinition warning message:

Warning: Some C++ language constructs in the files for generating interface file 
are not supported and not imported.

An example of information that the publisher must define relates to the use of pointers to pass data to functions. A pointer is a location in memory that indicates the start of a block of data. To pass this data to MATLAB safely, the publisher must specify the size of the data. The function documentation indicates the size of the data, perhaps as an additional input argument. Using the MATLAB definition file, the publisher specifies the value, and then MATLAB creates the equivalent MATLAB function signature. To display function signatures, see Display Help for MATLAB Interface to C++ Library.

After creating the library definition file definelibName.m using clibgen.generateLibraryDefinition, you might have to modify the contents to include functionality in the interface. Use the MATLAB Editor to modify the definition file. Replace the <DIRECTION>, <SHAPE>, and <MLTYPE> parameters with the missing information. These parameters are used for these cases.

  • To specify if a pointer argument is read-only input, output only, or a modifiable input argument, use the DIRECTION parameter.

  • If a pointer argument is used for array data, then dimension information is required to convert the array between C++ and MATLAB. Use the SHAPE parameter to specify this information.

  • C++ has many types representing string arguments. You might need to specify MLTYPE and SHAPE values so that MATLAB can correctly convert the C++ type to the MATLAB string type.

MATLAB offers code suggestions for values of these parameters. To activate suggestions for a specific parameter:

  • Uncomment the code defining the function. Do not uncomment the first two lines in the code section which contain the section title and the C++ signature help.

  • Delete the parameter name, including the <> characters.

  • Pause to allow the code suggestions to be displayed.

  • If the suggestions do not appear, make sure that the definelibName.m file is on your MATLAB path.

Autodefine Arguments

You can direct MATLAB to autodefine the type and shape of specific argument types by using clibgen.generateLibraryDefinition and clibgen.buildInterface name-value arguments. The options are:

When you validate the library definition, you might get errors about duplicate MATLAB signatures. To resolve these errors, see Reconcile MATLAB Signature Conflicts.

Reconcile MATLAB Signature Conflicts

After generating and editing a library definition file, there might be two or more functions or other constructs with identical MATLAB signatures. To check for this conflict, validate the definition file. For example, for the definition file definelibname, type:

definelibname

If there is a conflict, MATLAB displays an error with a link to the code in the definition file. To resolve the conflict, choose one of the following:

  • Revise the defineArgument or defineOutput arguments to create a unique MATLAB signature. The conflict occurs when there are multiple overloaded functions, and you specify the same argument parameters. See How to Complete Definitions in Library Definition File.

  • Remove one of the functions by commenting out the definition of the construct. The conflict might occur when you use one of the clibgen.generateLibraryDefinition name-value arguments to convert all cases of a particular type. You also can remove an overloaded function.

After modifying the definition file, rerun the file to validate your edits.

Customize Content

Review the renaming scheme used by MATLAB to replace invalid names. For more information, see C++ Names That Are Invalid in MATLAB.

Review autogenerated help. MATLAB copies some C++ comments into Description and DetailedDescription arguments. You can modify or replace this content, which is the basis of the doc command for end users.

Customize Function Template Names

Review the unique function names generated from function templates in the library definition file. For example, class A in this header file defines a function template show and provides instantiations for types int, double, and const A.

class A{}; // User type
template<typename T> void show(T a) {}
template void show<int>(int);
template void show<double>(double);
template<> void show<const A &>(const A& a){}

If you build an interface libname to this library, MATLAB creates overloaded functions that have signatures for these instantiations.

summary(definelibname)
MATLAB Interface to libname Library

Class clib.libname.A

  Constructors:
    clib.libname.A(clib.libname.A)
    clib.libname.A()

  No Methods defined

  No Properties defined

Functions
clib.libname.show(int32)
clib.libname.show(double)
clib.libname.show(clib.libname.A)

The C++ interface also generates unique function names based on the signature types. To view the unique names, use the TemplateUniqueName property.

d = definelibname;
d.Functions(1:3).TemplateUniqueName
ans = "clib.libname.show_int_"
ans = "clib.libname.show_double_"
ans = "clib.libname.show_AConst__"

You can customize these names in the library definition file. For example, change the name of the function for the class object clib.libname.show_AConst__. Restart MATLAB and edit definelibname.m. Locate the addFunction statement for the show_AConst__ function and change the "TemplateUniqueName" name-value argument. Replace show_AConst__ with a new name, for example showObjectA. Update the "Description" name-value argument by replacing clib.libname.show with the new name clib.libname.showObjectA and modifying the help text to read Representation of C++ function show for class A.

"Description", "clib.libname.showObjectA    Representation of C++ function show for class A.");
help clib.libname.showObjectA
 clib.libname.showObjectA    Representation of C++ function show for class A.

    Inputs
      a              read-only clib.libname.A

For more information, see Use Function and Member Function Templates.

Dimension Matching

If the number of dimensions of a MATLAB argument is larger than the corresponding C++ parameter, then MATLAB deletes singleton dimensions from the left until the number of dimensions matches each other. If all singleton dimensions are deleted and the MATLAB argument is larger than the C++ parameter, then MATLAB produces an exception.

If the number of dimensions of the MATLAB argument is smaller than the C++ parameter, MATLAB adds singleton dimensions. By default, MATLAB inserts singleton dimensions at the beginning of the argument. To insert singleton dimensions at the end of the argument, set AddTrailingSingletons to true in the defineArgument functions - defineArgument (ConstructorDefinition), defineArgument (FunctionDefinition), and defineArgument (MethodDefinition).

For example, a C++ library contains two functions that have input arguments in interface libname defined as follows:

void setImages(const uint8_t * images, int numOfImages, int height, int width);
% By default 'AddTrailingSingletons' is false
defineArgument(setImagesFunctionDefinition, "images", "uint8", "input", ...
    ["numOfImages", "height", "width"])
void setColorImage(const uint8_t * image, int height, int width, int colorDepth);

defineArgument(setColorImageFunctionDefinition, "image", "uint8", "input", ...
    ["height", "width", "colorDepth"], "AddTrailingSingletons", true)

In MATLAB, create an image array such that:

size(myImage)
ans =
     768   1024

When you call setImages, MATLAB adjusts the size of myImage to [1, 768, 1024].

setImages(myImage)

When you call setColorImage MATLAB adjusts the size of myImage to [768, 1024, 1].

setColorImage(myImage)

See Also

|

Related Topics