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.

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

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:

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)