Define Missing Direction Property

R2026b

When defining arguments in a MATLAB interface to a C++ library, MATLAB infers argument information from C/C++ header files. However, some C++ language constructs can have an ambiguous mapping to MATLAB. For example, C++, pointer arguments can be used to both pass and return data from a function. In such cases, you must provide missing direction information by using the Direction property of a clibgen.api.InputArgumentDefinition object.

The Direction property determines how the MATLAB interface represents arguments in the generated MATLAB function signature. You can set the Direction property to one of these values:

• "input" — Input argument only. If a pointer argument passes data to the function, then it must appear as an input argument in the MATLAB^® signature. The Direction value for C-string parameters must be "input".

• "output" — Output argument only. If a pointer argument retrieves data from the function, then it must appear as an output argument in the MATLAB signature.

• "inputoutput" — Input and output argument. If a pointer argument both passes and returns data, then it must appear as both an input argument and an output argument.

Note

MATLAB does not support output-only arguments that have default values. For such C++ arguments, define Direction as "input" or "inputoutput" in the clibgen.api.InputArgumentDefinition object.

Define Direction for Pointer Argument

Set the Direction property only for arguments whose MATLABType is a native MATLAB type, such as double or int32. Do not set Direction for clib types. Interface objects are always passed as input arguments. If a function updates the underlying C++ object, the changes are reflected in the MATLAB object after the function call.

For example, suppose that a C++ function passData has the following signature. From the signature alone, MATLAB cannot determine whether data is an input to the function, the return value of the function, or input that the function modifies and returns. You might need to reference the documentation of the C++ function to determine how the function uses the argument data.

void passData(double *data); 

Assuming data is a scalar double value, this table shows three possible MATLAB signatures and how to set the argument direction based on its role in the function. In the sample code, fcn is a clibgen.api.FunctionDefinition object.

C++ Role for data	MATLAB Signature	Set Argument Direction
data is input to the function.	passData(data)	arg = fcn.CPPInputs([fcn.CPPInputs.Name] == "data"); arg.Direction = "input";
data is output for the function.	[data] = passData()	arg = fcn.CPPInputs([fcn.CPPInputs.Name] == "data"); arg.Direction = "output";
data is an input and output parameter.	[data] = passData(data)	arg = fcn.CPPInputs([fcn.CPPInputs.Name] == "data"); arg.Direction = "inputoutput";

Define Direction for Multiple Pointer Arguments

For functions with multiple pointer arguments, you can define the direction of each argument independently. For example, suppose that C++ function calcXY has this signature:

void calcXY(double *data, double *X, double *Y);

Assuming the function uses data as an input parameter, and X and Y as both input and output parameters, this table shows the intended MATLAB signature and how to set the argument direction information.

C++ Role for Parameters	MATLAB Signature	Set Argument Direction
data is input to the function.	[X,Y] = calcXY(data,X,Y)	arg = fcn.CPPInputs([fcn.CPPInputs.Name] == "data"); arg.Direction = "input";
X and Y are input and output parameters.		argX = fcn.CPPInputs([fcn.CPPInputs.Name] == "X"); argX.Direction = "inputoutput"; argY = fcn.CPPInputs([fcn.CPPInputs.Name] == "Y"); argY.Direction = "inputoutput";