Pass C++ Structures to MATLAB Functions

Prerequisites

Before you begin, complete these prerequisite tasks:

Define Structures in C++ Header File

Create a C++ header file that defines the structures you want to pass to MATLAB. This example defines Position and Rectangle structures in a Shapes namespace. Save the structure definitions in a file named shapes.hpp.

#include <cstdint>

namespace Shapes {

    struct Position {
        uint64_t X = 0;
        uint64_t Y = 0;
    };

    struct Rectangle {
        Position UpperLeft;
        Position LowerRight;
    };

}

Build MATLAB Interface to Structures

Build a MATLAB interface to the structures you defined. Before building the interface, select the C++ compiler you want to use by running this command:

mex -setup C++

To build the interface, use a clibgen.api.InterfaceDefinition object. (since R2026b)

For this example, the code creates a folder named ShapesLib and builds the interface, ShapesLibInterface.dll, in this folder. The Position and Rectangle structures in C++ map to clib.ShapesLib.Shapes.Position and clib.ShapesLib.Shapes.Rectangle objects in MATLAB.

icfg = clibgen.api.InterfaceConfiguration("ShapesLib",HeaderFiles="shapes.hpp",IncludePath=pwd);
idef = clibgen.api.InterfaceDefinition(icfg);
idef.build;

Before R2026b: Build the interface using the clibgen.buildInterface function.

clibgen.buildInterface("shapes.hpp",InterfaceName="ShapesLib")

Add the interface folder to the MATLAB search path so that you can use the generated clib objects in MATLAB.

addpath("C:\cpp\work\ShapesLib")

Pass Structures to MATLAB Function Using Interface

You can pass C++ structures to MATLAB functions by using the interface you built. For example, create a MATLAB function, createRectangle, that uses the ShapesLib interface to create a Rectangle structure from two input Position structures. Save the function in a file named createRectangle.m.

function rect = createRectangle(pt1,pt2)
%CREATERECTANGLE - Create rectangle using MATLAB interface to C++
    arguments (Input)
        pt1 (1,1) clib.ShapesLib.Shapes.Position
        pt2 (1,1) clib.ShapesLib.Shapes.Position
    end

    arguments (Output)
        rect (1,1) clib.ShapesLib.Shapes.Rectangle
    end

    rect = clib.ShapesLib.Shapes.Rectangle();
    rect.UpperLeft = pt1;
    rect.LowerRight = pt2;
end

The arguments blocks in this function validate the clib input and output structures. These blocks are optional but enable autocompletion for the structures in the MATLAB Editor. These type validations also enable your C++ application to internally pass the structures by reference instead of copying them field by field from MATLAB to C++.

Call MATLAB Function from C++ Application

You can call MATLAB functions that use C++ structures from your C++ application. For example, write a C++ application, myMain.cpp, that creates a rectangle using the MATLAB function and the structures defined in the header file.

This application runs on Windows^® or Linux^®. Running this application on Mac requires changes to the application logic. For more details, see the Run Application on Mac Platforms section.

#include "MatlabEngine.hpp"
#include "shapes.hpp"

USING_TYPE_WITH_MATLAB(Shapes::Position, "ShapesLib");
USING_TYPE_WITH_MATLAB(Shapes::Rectangle, "ShapesLib");

int main()
{
    using namespace matlab::engine;

    // Start in-process MATLAB
    std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(MATLABApplicationMode::IN_PROCESS);

    // Add path to working folder and MATLAB interface to C++ library
    matlabPtr->feval<void>(u"addpath", std::string("C:/cpp/work"));
    matlabPtr->feval<void>(u"addpath", std::string("C:/cpp/work/ShapesLib"));

    // Define points using Position structure
    Shapes::Position pt1, pt2;
    pt1.X = 0;
    pt1.Y = 0;
    pt2.X = 10;
    pt2.Y = 5;

    // Create Rectangle structure using feval with createRectangle.m
    Shapes::Rectangle* rectPtr = matlabPtr->feval<Shapes::Rectangle*>(
        u"createRectangle", &pt1, &pt2);

    // Display rectangle data
    std::cout << "Upper left: (" << rectPtr->UpperLeft.X
              << ", " << rectPtr->UpperLeft.Y << ")" << std::endl;
    std::cout << "Lower right: (" << rectPtr->LowerRight.X
              << ", " << rectPtr->LowerRight.Y << ")" << std::endl;

    // Deallocate Rectangle structure
    delete rectPtr;
    return 0;
}

Build and Run Application

Build and run the C++ application. Before building the application, select the C++ compiler you want to use. You must select the same compiler you used earlier to build the MATLAB interface to the structures. At the MATLAB command prompt, run this command:

mex -setup -client engine C++

Build an executable file for the application. The compiler creates the executable named myMain in the same folder as your code.

mex -client engine myMain.cpp

From the operating system command line, run the application. To run this application, your run-time environment must be configured to find MATLAB libraries, as described in Requirements to Build C++ Engine Applications.

.\myMain

Upper left: (0, 0)
Lower right: (10, 5)

The application displays the rectangle points. To modify the application, update your myMain.cpp file, and then rebuild the executable and rerun it.

Application Variations

You can customize the application to return a different number of outputs, call the MATLAB function asynchronously, or run on Mac platforms.

FutureResult<Shapes::Rectangle*> future = matlabPtr->fevalAsync<Shapes::Rectangle*>(u"createRectangle", &pt1, &pt2);
    // Do other work while MATLAB executes
Shapes::Rectangle* rectPtr = future.get();

int appCode(int argc, char *argv[]) {
    using namespace matlab::engine;
    std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB(MATLABApplicationMode::IN_PROCESS);
    // Application code here
    return 0;
}

int main(int argc, char *argv[]) {
    return matlab::engine::runMacLoopInProcess(appCode, argc, argv);
}