Define MATLAB Interface for C/C++ Library

R2026b

MATLAB^® represents a C/C++ library interface using a clibgen.api.InterfaceDefinition object. This object defines how C/C++ functions, data types, and constructs map to MATLAB function signatures.

You create and modify an InterfaceDefinition object programmatically from a clibgen.api.InterfaceConfiguration object. MATLAB infers much of the interface directly from C/C++ header files, but some language constructs do not have a direct or unambiguous mapping to MATLAB. In these cases, you must supply additional information by setting properties on the definitions in the object.

To identify these constructs, review the IncompleteClasses and IncompleteFunctions properties of the InterfaceDefinition object. A ClassDefinition object has a HasIncompleteMembers property. To identify these members, review the IncompleteMethods, IncompleteProperties and IncompleteConstructors properties.

Complete Definitions in InterfaceDefinition Object

After creating an InterfaceDefinition object, review the generated definitions and update any incomplete arguments or outputs.

Some C/C++ constructs require additional specification because MATLAB cannot infer key properties automatically. A common example is pointer-based arguments. A pointer identifies a location in memory that represents scalar data or an array. To pass this data safely between MATLAB and C/C++, you must define how to interpret the data.

To complete these definitions, set properties on the corresponding argument or output in the InterfaceDefinition object:

• Use the Direction property to specify whether an argument is input, output, or modified input. For more information, see Define Missing Direction Property.

• Use the Size property to define the dimensions of array data associated with pointer arguments. For more information, see Define Missing Size Property.

• Set the MATLABType property to control how C/C++ types are represented in MATLAB, such as mapping character pointers to MATLAB string types. For more information, see Define Missing MATLABType Property.

For example, when a function uses a pointer to pass array data, you must define both the direction of data flow and the expected size. In some cases, the required size information is documented as a separate input argument in the C/C++ function signature.

After updating the necessary properties, validate the InterfaceDefinition object to verify that all definitions are complete and consistent. MATLAB then uses the completed definitions to generate MATLAB function signatures for the interface.

Autodefine Arguments

When creating an InterfaceDefinition object, you can configure MATLAB to automatically define certain argument properties based on common C/C++ patterns. These options control how MATLAB assigns properties such as type and size during initial definition. To specify these behaviors, use these properties of the InterfaceConfiguration object.

• To represent const character pointers in the library as null-terminated C strings, set TreatConstCharPointerAsCString to true.

  idef.TreatConstCharPointerAsCString = true;

• To treat object pointers as scalar values, set TreatObjectPointerAsScalar to true.

  idef.TreatObjectPointerAsScalar = true;

These settings determine how MATLAB initializes argument properties in the InterfaceDefinition object. After generation, review the resulting definitions and update any properties that require more specific control.

Reconcile MATLAB Signature Conflicts

After creating and updating an InterfaceDefinition object, multiple functions or constructs might resolve to identical MATLAB signatures. These conflicts typically occur when overloaded C/C++ functions map to the same combination of MATLAB argument types and sizes.

To resolve signature conflicts, modify argument properties, such as Direction, Size, or MATLABType properties, to produce distinct MATLAB signatures for each definition.

Alternatively, if one of the conflicting definitions is not required in the MATLAB interface, remove it.

Customize Content

After creating an InterfaceDefinition object, you can optionally refine the names and descriptive content associated with the interface. MATLAB assigns default names when converting C/C++ constructs to MATLAB identifiers. These names are based on the original C/C++ symbols and might be modified to meet MATLAB naming requirements. Review the renaming scheme used by MATLAB to replace invalid names. For more information, see C++ Names That Are Invalid in MATLAB.

MATLAB also populates Description and DetailedDescription properties using comments extracted from the C/C++ header files. These properties provide the basis for function help displayed in MATLAB. You can modify or replace this content to provide clearer or more complete documentation for end users.

Customize Function Template Names

C++ function templates can produce multiple MATLAB functions when instantiated with different types. Each instantiation is represented as a separate function in the InterfaceDefinition object, based on the corresponding type-specific signature.

MATLAB generates unique names for these functions to distinguish between different template instantiations. These generated names are derived from the function signature and type information. You can customize these names by updating the corresponding function definitions in the InterfaceDefinition object. For each function, modify the MATLABName property that controls the unique function name to assign a more meaningful or user-friendly name.

Dimension Matching

The number of dimensions of MATLAB input data must align with the expected dimensions of corresponding C/C++ parameters. When they differ, MATLAB adjusts the input based on the size information defined in the InterfaceDefinition object.

The Size property specifies how MATLAB interprets the dimensions of the data. This property determines how MATLAB reshapes inputs to match the expected C/C++ representation.

• If a MATLAB input has more dimensions than the corresponding C/C++ parameter, MATLAB removes leading singleton dimensions until the number of dimensions matches.

• If all singleton dimensions are removed and the MATLAB input still has more dimensions than expected, MATLAB displays an error.

• If a MATLAB input has fewer dimensions than the corresponding C/C++ parameter, MATLAB adds singleton dimensions.

By default, MATLAB adds singleton dimensions at the beginning of the argument. To append singleton dimensions at the end instead, set the AddTrailingSingletons property to true on the corresponding argument definition in the InterfaceDefinition object.

For example, consider a C/C++ function that expects image data with multiple dimensions. When defining the corresponding argument, use the Size property to associate the argument with dimension inputs, and set AddTrailingSingletons as needed to control how MATLAB adjusts the dimensions of input data.