Integrate Strongly Typed MATLAB Data in C++ Application

This example shows how to create a C++ header file from a strongly typed MATLAB^® function and integrate it with sample C++ application code. Using argument declarations in your MATLAB function enforces a strict data type mapping between MATLAB and C++, which lets you call MATLAB functions and classes by their MATLAB names in C++ as if they were native C++ functions and classes.

Prerequisites

Verify that you have set up a C++ development environment. For details, see Set Up C++ Development Environment.
Verify that you have a C++ compiler installed by entering this statement at the MATLAB command prompt:
```
mex -setup -client engine C++
```
Verify that you have met all of the requirements to build a C++ program using the MATLAB Engine API for C++. For details, see Requirements to Build C++ Engine Applications.

Create MATLAB Function

Create a MATLAB file named calculateDistance.m with this code.

function distance = calculateDistance(p1, p2)
    % This function calculates the Euclidean distance between two points
    % Inputs:
    %   p1 - a two-element vector [x, y]
    %   p2 - a two-element vector [x, y]
    % Output:
    %   distance - the Euclidean distance between p1 and p2
    
    % Use arguments block to map C++ type to corresponding MATLAB type
    % std::vector<int32_t> <--> (1,2) int32 {mustBeReal}
    
    arguments (Input)
        p1 (1,2) int32 {mustBeReal}
        p2 (1,2) int32 {mustBeReal}
    end

    arguments (Output)
        distance (1,1) int32 {mustBeReal}
    end
    
    % Calculate Euclidean distance
    diff = p1 - p2;
    diffSq = diff.^2;
    sumSq = sum(diffSq);
    distance = sqrt(sumSq);
end

The arguments block lets you represent C++ data types with an equivalent MATLAB type. For instance, if your C++ application uses an int32_t data type to represent a value, you can represent that value in MATLAB as an int32 value. This option is useful in situations where a C++ application has strict type requirements. For details, see Data Type Mappings Between C++ and Strongly Typed MATLAB Code.

Incorporating an arguments block is optional. If data types are not crucial in your application, the specification of type information using an arguments block is not necessary.

Test the MATLAB function at the command prompt.

p1 = int32([0 0])
p2 = int32([3 4])
distance = calculateDistance(p1,p2)

p1 =
  1×2 int32 row vector
   0   0
p2 =
  1×2 int32 row vector
   3   4
distance =
  int32
   5

Generate C++ Header File

Create a header (.hpp) file from the MATLAB function using the matlab.engine.typedinterface.generateCPP function.

matlab.engine.typedinterface.generateCPP("calculateDistance.hpp", ...
    Functions="calculateDistance")

The function creates the header file calculateDistance.hpp in the current folder.

calculateDistance.hpp

In the calculateDistance.hpp header, the MATLAB function's int32 argument specification mirrors its C++ equivalent, int32_t.

function distance = calculateDistance(p1, p2)
    % ...
    arguments (Input)
        p1 (1,2) int32 {mustBeReal}
        p2 (1,2) int32 {mustBeReal}
    end
    % ...
end

std::vector<int32_t> p1, 
std::vector<int32_t> p2

function distance = calculateDistance(p1, p2)
    % ...
    arguments (Output)
       distance (1,1) int32 {mustBeReal}
    end    
    % ...
end

template<>
struct return_type_calculateDistance<1> { typedef int32_t type; };
...
...
matlab::data::Array _result_mda = _matlabPtr->feval(u"calculateDistance", _args);
int32_t _result;
_result = MatlabTypesInterface::convertMDAtoScalar<int32_t>(_result_mda);

Integrate MATLAB Header File into C++ Application

This example uses MATLAB as a C++ development environment. Use an #include directive to incorporate the generated header file in your C++ application code. You can use this sample C++ application code as a guide when writing your own application.

DistanceConsoleApp.cpp

Build C++ Application

Compile and link the C++ application at the MATLAB command prompt.

mex -client engine DistanceConsoleApp.cpp

Run C++ Application

To run your application, be sure to first configure your run-time environment by adding the specified path to the appropriate environment variable. For more information, see Run-Time Environment. For example, if your matlabroot on Windows^® is C:\Program Files\MATLAB\R2024a, then this system prompt command sets the run-time environment variable:

set PATH=C:\Program Files\MATLAB\R2024a\extern\bin\win64;%PATH%

Then run the application.

DistanceConsoleApp

MATLAB returns the Euclidean distance to the C++ program, and then the C++ program displays the results.

Euclidean distance between [0, 0] and [3, 4] is: 5