Define Missing SHAPE Parameter - MATLAB & Simulink (original) (raw)

In C++, pointer arguments are used for both scalar data and array data. To use a pointer as an array, MATLAB® needs dimension information to safely convert the array between C++ and MATLAB. The SHAPE parameter helps you specify the dimensions for the pointer.

Note

Pointers representing arrays of C++ class objects can only be used as scalars. Define SHAPE as 1 in the library definition file.

The following example C++ signatures show you how to specify the shape of an argument. In these tables, the descriptions for the functions in the C++ Signature and Role of Pointer column are based on assumed knowledge of the arguments. The signature itself does not provide this information.

Define Pointer Argument to Fixed Scalar

C++ Signature and Role of Pointer	defineArgument Values
The input to this function is a scalar pointerin.void readScalarPtr(int const * in)	For argument in, set SHAPE to1.defineArgument(readScalarPtrDefinition, "in", ... "int32", "input", 1);
The input to this function is a scalar pointer to classns::MyClass2.void readScalarPtr(ns::MyClass2 const * in)	For argument in, set SHAPE to1.defineArgument(readScalarPtrDefinition, "in", ... "clib.cppUseCases.ns.MyClass2", "input", 1);

Define Pointer Argument

C++ Signature	defineArgument Values
The input to this function is a pointer to an integer array of lengthm.void readMatrix1DPtr(int const * mat, size_t m)	For argument mat, set SHAPE to argumentm.defineArgument(readMatrix1DPtrDefinition, "mat", ... "int32", "input", "m");
The input to this function is a pointer to a fixed-length arraymat.void readMatrix1DPtrFixedSize(int const * mat)	For argument mat, set SHAPE to a fixed integer, such as 5.defineArgument(readMatrix1DPtrFixedSizeDefinition, ... "mat", "int32", "input", 5);
The input to this function is a pointer to a two-dimensional integer matrix mat of sizem-by-n.void readMatrix2DPtr(int const * mat, size_t m, size_t n)	For argument mat, set SHAPE to["m","n"].defineArgument(readMatrix2DPtrDefinition, "mat", ... "int32", "input", ["m","n"]);
The input to this function is a pointer to a two-dimensional matrixmat of fixed dimensions.void readMatrix2DPtrFixedSize(int const * mat)	For argument mat, set SHAPE to a fixed integer, such as 6.defineArgument(readMatrix2DPtrFixedSizeDefinition, ... "mat", "int32", "input", 6);
The input to this function is a pointer to a three-dimensional matrixmat of sizem-by-n-by-p.void readMatrix3DPtr(int const * mat, size_t m, size_t n, size_t p)	For argument mat, set SHAPE to["m","n","p"].defineArgument(readMatrix3DPtrDefinition, "mat", ... "int32", "input", ["m","n","p"]);

Define Array Argument

C++ Signature	defineArgument Values
The input to this function is a one-dimensional arraymat of lengthlen.void readMatrix1DArr(int const [] mat, size_t len)	For argument mat, set SHAPE to lengthlen.defineArgument(readMatrix1DArrDefinition, "mat", ... "int32", "input", "len");
The input to this function is a two-dimensional arraymat of size len bytypeSz.void readMatrix2DArr(int const [] mat, size_t len, size_t typeSz)	For argument mat, set SHAPE to["len","typeSz"].defineArgument(readMatrix2DArrDefinition, "mat", ... "int32", "input", ["len","typeSz"]);

Define Output Pointer Argument

C++ Signature	defineArgument Values
The input to this function is a pointer to an array of lengthlen. The function returns a pointer argument as output.int const * getRandomValues(size_t len)	For the return value RetVal, setSHAPE to argumentlen.defineOutput(getRandomValuesDefinition, "RetVal", ... "int32", "len");
The input to this function is a pointer to an array of lengthlen. The library provides a function namedCustomDeleteFcn which MATLAB can use to manage the memory of the argument.int const * getRandomValues(size_t len)	For the return value RetVal, setSHAPE to argument len. SpecifyCustomDeleteFcn as the DeleteFcn argument.defineOutput(getRandomValuesDefinition, "RetVal", ... "int32", "len", "DeleteFcn", "CustomDeleteFcn");
The output argument of this function is a pointer to a fixed-length array.int const * getRandomValuesFixedSize()	For the return value RetVal, setSHAPE to an integer, such as 5.defineOutput(getRandomValuesFixedSizeDefinition, ... "RetVal", "int32", 5);
The output argument of this function is a pointer to a 2-by-2 array.double * getRandomValuesArray()	For the return value RetVal, setSHAPE to a [2, 2] array.defineOutput(getRandomValuesArrayDefinition, ... "RetVal", "double", [2,2]);
The output argument of this function is a pointer to a 1-by-2 vector of type double. The library provides a function namedCustomDeleteFcn which MATLAB can use to manage the memory of the argument.double * getRandomValuesDouble()	For the return value RetVal, setSHAPE to 2. Specify CustomDeleteFcn as theDeleteFcn argument.defineOutput(getRandomValuesDoubleDefinition, ... "RetVal", "double", 2, "DeleteFcn", "CustomDeleteFcn");
The output argument of this function is a pointer to a 1-by-2 vector of type const double. The library provides a function namedCustomDeleteFcn which MATLAB can use to manage the memory of the argument.double const * getRandomConstDouble()	For the return value RetVal, setSHAPE to 2. Specify CustomDeleteFcn as theDeleteFcn argument.defineOutput(getRandomConstDoubleDefinition, ... "RetVal", "double", 2, "DeleteFcn", "CustomDeleteFcn");

Define Additional Output Arguments

C++ Signature	defineArgument Values
This function returns an integer value and the value to which input argument arg points.int getValues(int * arg)	For argument arg, change DIRECTION to "output", change MLTYPE to"int32", and set SHAPE to 1.defineArgument(getValuesDefinition, "arg", "int32", "output", 1);
To call the function built into interfaceA from MATLAB, type:[out1, out2] = clib.A.getValues

Define Scalar Object Argument

C++ Signature	defineArgument Values
The input to this function is a pointer to classns::MyClass2.double addClassByPtr(ns::MyClass2 const * myc2)	For the myc2 argument, set SHAPE to1.defineArgument(addClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);
The input to this function is a pointer to classns::MyClass2.void updateClassByPtr(ns::MyClass2 * myc2, double a, short b, long c)	For argument myc2, set SHAPE to1.defineArgument(updateClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);
The input to this function is a pointer to classns::MyClass2.void readClassByPtr(ns::MyClass2 * myc2)	For argument myc2, set SHAPE to1.defineArgument(readClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);
The input to this function is a pointer to classns::MyClass2.void fillClassByPtr(ns::MyClass2 * myc2, double a, short b, long c)	For argument myc2, set SHAPE to1.defineArgument(fillClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);

Define Matrix Argument

C++ Signature	defineArgument Values
The input to this function is a pointer to an integer vector of lengthlen. The argument x modifies the input argument.void updateMatrix1DPtrByX(int * mat, size_t len, int x)	For argument mat, set DIRECTION to"inputoutput" and SHAPE to"len".defineArgument(updateMatrix1DPtrByXDefinition, ... "mat", "int32", "inputoutput", "len");
The input to this function is a reference to an integer array of lengthlen. Argument x modifies input argumentmat.void updateMatrix1DArrByX(int [] mat, size_t len, int x)	For argument mat, set DIRECTION to"inputoutput" and SHAPE to"len".defineArgument(updateMatrix1DArrByXDefinition, ... "mat", "int32", "inputoutput", "len");
The input to this function is a pointer to an integer vector of lengthlen. The function does not modify the input argument.int addValuesByPtr(int * mat, size_t len)	For argument mat, set DIRECTION to"input" and SHAPE to"len".defineArgument(addValuesByPtrDefinition, "mat", ... "int32", "input", "len");
The input to this function is a reference to an integer array of lengthlen. The function does not modify the input argument.int addValuesByArr(int [] mat, size_t len)	For argument mat, set DIRECTION to"input" and SHAPE to"len".defineArgument(addValuesByArrDefinition, ... "mat", "int32", "input", "len");
This function creates an integer vector of length len and returns a reference to the vector.void fillRandomValuesToPtr(int * mat, size_t len)	For argument mat, set DIRECTION to"output" and SHAPE to"len".defineArgument(fillRandomValuesToPtrDefinition, ... "mat", "int32", "output", "len");
This function creates an integer vector of length len and returns a reference to the vector.void fillRandomValuesToArr(int [] mat, size_t len)	For argument mat, set DIRECTION to"output" and SHAPE to"len".defineArgument(fillRandomValuesToArrDefinition, ... "mat", "int32", "output", "len");

Define String Argument

C++ Signature	defineArgument Values
The input to this function is a C-style string.char const * getStringCopy(char const * str)	For argument str, set MLTYPE to"string" and SHAPE to"nullTerminated".defineArgument(getStringCopyDefinition, "str", ... "string", "input", "nullTerminated");
The return value for this function is a string.char const * getStringCopy(char const * str)	For return value RetVal, set MLTYPE to "string" and SHAPE to"nullTerminated".defineOutput(getStringCopyDefinition, ... "RetVal", "string", "nullTerminated");
The return value for this function is a string of lengthbuf.void getMessage(char * pmsg, int buf)	MATLAB defines argument pmsg as an input variable of typeclib.array.libname.Char.%defineArgument(getMessageDefinition, "pmsg", ... "clib.array.libname.Char", "input", ); To define pmsg as an output variable of type string:Replace "input" with"output".Replace the type with "string" and set to "nullTerminated".Add the "NumElementsInBuffer" name-value argument set to variable buf.defineArgument(getMessageDefinition, "pmsg", ... "string, "output", "nullTerminated", ... "NumElementsInBuffer", "buf");
The input to this function is a string specified by lengthlen.void readCharArray(char const * chArray, size_t len)	For argument chArray, set MLTYPE to"char" and SHAPE to"len".defineArgument(readCharArrayDefinition, ... "chArray", "char", "input", "len");
The input to this function is an array of type int8 and lengthlen.void readInt8Array(char const * int8Array, size_t len)	For argument int8Array, set MLTYPE to "int8" and SHAPE to"len".defineArgument(readInt8ArrayDefinition, ... "int8Array", "int8", "input", "len");
The return value for this function is a scalar of characters.char const * getRandomCharScalar()	For return value RetVal, set MLTYPE to "char" and SHAPE to1.defineOutput(getRandomCharScalarDefinition, ... "RetVal", "char", 1);
The return value for this function is a 2 element character vector.char * getRandomChars()	For return value RetVal, set MLTYPE to "char" and SHAPE to2.defineOutput(getRandomCharsDefinition, ... "RetVal", "char", 2);
The return value for this function is a 2 element character vector. The library provides a function named CustomDeleteFcn which MATLAB can use to manage the memory of the argument.char * getRandomChars()	For return value RetVal, set MLTYPE to "char" and SHAPE to 2. Specify CustomDeleteFcn as the DeleteFcn argument.defineOutput(getRandomCharsDefinition, ... "RetVal", "char", 2 "DeleteFcn", "CustomDeleteFcn");
The type of the return value for this function isint8.char const * getRandomInt8Scalar()	For return value RetVal, set MLTYPE to "int8" and SHAPE to1.defineOutput(getRandomInt8ScalarDefinition, ... "RetVal", "int8", 1);
This function updates the input argument chArray. The length of chArray islen.void updateCharArray(char* chArray, size_t len)	For argument chArray, set DIRECTION to "inputoutput" and SHAPE to"len".defineArgument(updateCharArrayDefinition, ... "chArray", "int8", "inputoutput", "len");
The input to these functions is an array of C-string of sizenumStrs.void readCStrArray(char** strs, int numStrs);void readCStrArray(char* strs[], int numStrs);	For argument strs, set SHAPE to the array ["numStrs", "nullTerminated"].defineArgument(readCStrArrayDefinition, ... "strs", "string", "input", ["numStrs", "nullTerminated"])
The input to these functions is a const array of C-string of sizenumStrs.void readConstCStrArray (const char** strs, int numStrs);void readConstCStrArray (const char* strs[], int numStrs);	Call clibgen.generateLibraryDefinition withTreatConstCharPointerAsCString set to true to automatically define SHAPE for argument strs as["numStrs", "nullTerminated"].defineArgument(readConstCStrArrayDefinition, ... "strs", "string", "input", ["numStrs", "nullTerminated"])
The input to this function is a fixed-size array of C-string.void readFixedCStrArray (char* strs[5]);	For argument strs, set SHAPE to the array [5, "nullTerminated"].defineArgument(readFixedCStrArrayDefinition, ... "strs", "string", "input", [5, "nullTerminated"])
The input to this function is a fixed-size const array of C-string.void readConstCFixedStrArray (const char* strs[5]);	Call clibgen.generateLibraryDefinition withTreatConstCharPointerAsCString set to true to defineSHAPE for argument strs as [5, "nullTerminated"].defineArgument(readConstFixedCStrArrayDefinition, ... "strs", "string", "input", [5, "nullTerminated"])

Define Typed Pointer Argument

C++ Signature	defineArgument Values
The input to this function is a pointer to typedefintDataPtr.void useTypedefPtr(intDataPtr input1) intDataPtr is defined as:typedef int16_t intData; typedef intData * intDataPtr;	For argument input1, set DIRECTION to input and SHAPE to1.defineArgument(useTypedefPtrDefinition, "input1", ... "int16", "input", 1);

Use Property or Method as `SHAPE`

You can use a public nonstatic C++ data member (property) as theSHAPE for the return type of a nonstatic method or another nonstatic data member (property) in the same class. The property must be defined as an integer (C++ type int). Similarly, you can use a static C++ data members as aSHAPE parameter for a return type of a static method or another static data member in the same class.

You can use a public, nonstatic C++ method as the SHAPE parameter for a nonstatic property or for the return type of a nonstatic method in the same class. The method must be fully implemented, without input arguments, and the return type must be defined as a C++ type int.

You can use a combination of parameters, properties and methods as theSHAPE parameter for a method return type. If the specifiedSHAPE exists as both a parameter and a method or property, then parameters take precedence. In this case SHAPE is treated as a parameter.

C++ Signature	SHAPE Values
The size of data member rowData is defined by data members rows and cols and by the result of method channels.class A { public: int rows; int cols; int* rowData; int channels(); };	For property rowData, set SHAPE to an array of rows, cols, andchannels.addProperty(ADefinition, "rowdata", ["rows","cols","channels"]... "Description", "clib.array.libname.Int Data member of C++ class A.");
The size of the array returned by getData is defined by data members rows and cols and by the result of the channels method.class B { public: int rows; int cols; int* rowData; int channels(); const int* getData(); };	For the return value of method getData, setSHAPE to an array of rows,cols, andchannels.defineOutput(getDataDefinition, "RetVal", "clib.array.libname.Int", ... ["rows","cols","channels"]);
The size of the array returned by getData is defined by the rows parameter and the result of methodchannels.class C { public: int rows; int channels(); const int* getData (int rows); };	For the return value of method getData, setSHAPE to an array of parameter rows and methodchannels.defineOutput(getDataDefinition, "RetVal", "clib.array.C.Int", ["rows","channels"]);