Define void* and void** Arguments

Define `void*` and `void**` Arguments

MATLAB^® supports C++ signatures that have void* inputs or that return void* outputs. A void* return type and a void** parameter type are opaque objects.

You cannot create void* and void** types in MATLAB. Instead, you can use C++ library functions with these types:

If void* is defined with a typedef (or using) keyword, then MATLAB assigns the typedef name as the MLTYPE.
Publishers can assign a MATLAB type to a void* type by specifying MLTYPE in the library definition file.
MATLAB users can pass a void* return argument as input to a function that takes the appropriate void* input.

MATLAB returns a void* return type for void** parameters. For more information, see void** Input Argument Types.

MATLAB does not support type-casting void* to MATLAB data types.

`void*` Return Types

MATLAB defines void* output in the library definition file by specifying the argument MLTYPE as one of these:

A typedef from the library. Use for scalar output only.
If void* has a typedef defined in the library, MATLAB specifies MLTYPE as the new type name in the typedef statement.
If there is no typedef, chose a MATLAB type of the format clib.InterfaceName.TypeName, where TypeName can include a namespace.
If the library does not have an appropriate typedef statement, you can define void* with a MATLAB type.

This sample header file contains functions with void* types. You can define these types by using statements from the generated library definition file for the example. Assumptions about the argument types are based on the library documentation.

typedef void* handle; 
handle getHandle();   

using ghandle = void*;
ghandle getGHandle(); 

void* getImagData(const int* pa);

typedef void* data; 
void* getData();

Define Output Argument by Using `typedef` from Library

handle is defined by typedef. MATLAB creates the opaque type typedef void* handle.

addOpaqueType(libnameDef, ...
    "typedef void* handle", "MATLABName", ...
    "clib.libname.handle", ... 
    "Description", "clib.libname.handle Representation of C++ type void*.")

MATLAB automatically uses this type to define MLTYPE as clib.libname.handle in the return argument.

defineOutput(getHandleDefinition, "RetVal", "clib.lib.handle");

Define Output Argument from `using` Statement

ghandle is defined with a using statement. As with handle in the previous example, MATLAB automatically creates type typedef void* ghandle and uses it to define MLTYPE as clib.libname.ghandle in the return argument.

addOpaqueType(libnameDef, ...
    "typedef void* ghandle", "MATLABName", ...
    "clib.libname.ghandle", ... 
    "Description", "clib.libname.ghandle Representation of C++ type void*.")
defineOutput(getGHandleDefinition, "RetVal", "clib.libname.ghandle");

Define Output Argument from New Type Name

The output of getImagData needs definition.

%defineOutput(getImagDataDefinition, "RetVal", <MLTYPE>, <SHAPE>); ...
%'<MLTYPE>' can be an existing typedef name for void* or a new typedef name to void*.

You can specify a new type, for example clib.libname.ImagData and use it to define RetVal as a scalar value of this type.

defineOutput(getImagDataDefinition, "RetVal", "clib.libname.ImagData", 1);

Define Output Argument from Existing `typedef`

The output of getData needs definition.

%defineOutput(getDataDefinition, "RetVal", <MLTYPE>, <SHAPE>); 
%'<MLTYPE>' can be an existing typedef name for void* or a new typedef name to void*.

Because there is a typedef for void* named data, you can use this to define RetVal as a scalar value of type clib.libname.data.

defineOutput(getDataDefinition, "RetVal", "clib.libname.data", 1);

`void*` Input Argument Types

MATLAB attempts to convert the underlying C++ data of a void* argument to the corresponding C++ type. For information about the C++ to MATLAB data type mapping, see void* Argument Types.

Fundamental types
clib.array types
Types for C++ classes in the library
void* typedef

Following are sample header file statements containing functions that have void* input arguments. Assumptions about the argument types are based on the library documentation. The defineArgument statements in the generated library definition file definelibname.m show you how to treat each case.

Define Input Argument as Fundamental Type

The documentation for getAttribute indicates that void *value points to C++ data of fundamental type uint64_t and that this value is passed as a return argument.

class TaskHandle; 
int32 getAttribute(TaskHandle tHandle, int32 attribute, void *value);

MATLAB generates this statement for defining input argument value.

%defineArgument(getAttributeDefinition, "value", <MLTYPE>, <DIRECTION>, <SHAPE>); 
%'<MLTYPE>' can be primitive type, user-defined type, clib.array type, or 
%a list of existing typedef names for void*.

Define value as a scalar return value of type uint64.

defineArgument(getAttributeDefinition, "value", "uint64", "output", 1);

Define Input Argument as `clib.array` Type

You can define the readArray argument in this readRaw function as a clib.array type.

class TaskHandle; 
int32 readRaw (TaskHandle tHandle, void *readArray, uInt32 arraySizeInBytes);

Define argument void *readArray as an input of type clib.array.libname.Int with a size of arraySizeInBytes.

defineArgument(readRawDefinition, "readArray", "clib.array.libname.Int", ...
    "input", "arraySizeInBytes");

Define Input Argument as C++ Class in Library

You can define the userdata argument in this setDrawCallback function as a class in the library.

void setDrawCallback(const String& winname, 
    OpenGlDrawCallback onOpenGlDraw, 
    void* userdata = 0) 
void on_opengl(void* param) { 
cv::ogl::Texture2D* backgroundTex = (cv::ogl::Texture2D*)param; 
.... 
}

Define argument void *userdata as an input scalar of class clib.lib.cv.ogl.Texture2D.

defineArgument(setDrawCallbackDefinition, "userdata", "clib.lib.cv.ogl.Texture2D", ...
    "input", 1);

Define Input Argument as Existing `void*` `typedef`

You can define the in argument in this setRemoteTimeout function by using an existing typedef for void*.

typedef void* sessionHandle; 
void setRemoteTimeout(sessionHandle in);

Define argument in as an input scalar of typedef sessionHandle.

defineArgument(setRemoteTimeoutDefinition, "in", "clib.libname.sessionHandle", "input", 1);

`void**` Input Argument Types

MATLAB returns a void* argument for void** parameters. If void * is defined by using a typedef or a using statement, then MATLAB automatically assigns the typedef or using name as the MLTYPE. Otherwise, you can assign a MATLAB type to an existing void* type in the library by specifying MLTYPE in the library definition file.

This sample header file contains functions with void** parameters. The following topics show you how you can define these types by using statements from the generated library definition file for the example. Assumptions about the argument types are based on the library documentation.

class HClass{};
typedef void* handle; 
void getHandle(handle* out){
    *out = new HClass();
}
using ghandle = void*;
void getGHandle(ghandle* out){
    *out = new HClass();
}

void getNewHandle(void** out){
    *out = new int(1);
}
typedef void* ptr; 
void getPointer(void** out){
    *out = new int(2);
}

Define Argument With `void*` `typedef` or `using` Statement From Library

The out argument in the getHandle function is defined as a pointer to the void* type handle. For interface library lib, MATLAB uses the existing typedef statement to define out as an output scalar of type clib.lib.handle.

defineArgument(getHandleDefinition, "out", "clib.lib.handle", "output", 1);

The out argument in the getGHandle function is defined as a pointer to the void* variable ghandle defined by a using statement. MATLAB uses the existing using statement to define out as an output scalar of type clib.lib.ghandle.

defineArgument(getGHandleDefinition, "out", "clib.lib.ghandle", "output", 1);

Define Argument From New Type Name for `void*`

The void** parameter of getNewHandle needs definition.

%defineArgument(getNewHandleDefinition, "out", <MLTYPE>, "output", 1);

You can specify a new type, for example clib.lib.NewHandle.

defineArgument(getNewHandleDefinition, "out", "clib.lib.NewHandle", "output", 1);

Define Argument From Existing `void*` `typedef`

The void** parameter of getNewHandle needs definition.

%defineArgument(getPointerDefinition, "out", <MLTYPE>, "output", 1);

Because there is a typedef for void* named ptr, you can use this to define the out parameter as a scalar value of type clib.lib.ptr.

defineArgument(getPointerDefinition, "out", "clib.lib.ptr", "output", 1);

`MATLABType` as Object of Class

MATLAB displays a message about an object not available without constructing an object of the class and suggests other values for MATLABType. Alternatively, consider using a MATLABType that is outside the scope of the class.

For example, suppose that you create a library definition file definelib.m from this class A.

class A {
public:
	typedef void* handle;
	A(void* arg1, handle arg2) {}

	void* task1() {
		int* x = new int(10);
		return x;
	}

	handle task2() {
		int* x = new int(10);
		return x;
	}
};

MATLAB creates an opaque type for typedef void* handle and defines task2. The publisher creates an opaque type clib.lib.A.NewHandle for void* task1 and the A class constructor argument void* arg1.

addOpaqueType(libDef, "typedef void* A::handle", "MATLABName", "clib.lib.A.handle ", ...
"Description", "clib.lib.A.handle Representation of C++ opaque type.");

AConstructor1Definition = addConstructor(ADefinition, ...
"A::A(void * in)", ...
"Description", "clib.lib.A.A Constructor of C++ class A.");
defineArgument(AConstructor1Definition, "arg1", "clib.lib.A.NewHandle", "input", 1); 
% '<MLTYPE>' can be primitive type, user-defined type, clib.array type, or a list of existing typedef names for void*.
defineArgument(AConstructor1Definition, "arg2", "clib.lib.A.handle", "input", 1); 
% '<MLTYPE>' can be clib.lib.A.handle, primitive type, user-defined type, or a clib.array type.
validate(AConstructor1Definition);

task1Definition = addMethod(ADefinition, ...
"A::handle A::task1()", ...
"Description", "clib.lib.A.task1 Method of C++ class A.");
defineOutput(task1Definition, "RetVal", "clib.lib.A.NewHandle", 1); 
% '<MLTYPE>' can be an existing typedef name for void* or a new typedef name to void*.
validate(task1Definition);

task2Definition = addMethod(ADefinition, ...
"A::handle A::task2()", ...
"Description", "clib.lib.A.task2 Method of C++ class A.");
defineOutput(task2Definition, "RetVal", "clib.lib.A.handle", 1);
validate(task2Definition);

Because there is more than one void* input argument for constructor A, MATLAB displays this message:

clib.lib.A(clib.lib.A.Newhandle,clib.lib.A.handle)
      Note: This constructor cannot create object clib.lib.A, if object clib.lib.A.Newhandle/ 
      clib.lib.A.handle is not available without constructing object of clib.lib.A. 
      Consider using a MATLABType which is outside the scope of clib.lib.A.

To create a clib.lib.A object for this constructor, specify MATLABType as one of these:

Primitive type, user-defined type, or clib.array type for arg1.
Primitive type, user-defined type, clib.array type for arg2.
MATLABType, which is outside the scope of clib.lib.A.

Memory Management for `void*` and `void**` Arguments

You can pass the ownership of the memory of a void* argument to the library by using the ReleaseOnCall name-value argument in defineArgument (FunctionDefinition) or defineArgument (MethodDefinition).

You can transfer ownership of the memory of a void* output to MATLAB by using the DeleteFcn name-value argument in defineOutput (FunctionDefinition) or defineOutput (MethodDefinition). The deleter can be a user-defined function or the C++ standard delete operator for void* return types.

For scalar void** output arguments, use the DeleteFcn argument in defineArgument (FunctionDefinition) or defineArgument (MethodDefinition). For an example, see Manage Memory of Double Pointer Input Argument.

If you have multiple void* typedef statements, it is possible to define a deleter function that takes a list of these typedef arguments as the MLTYPE for void* input. If you assign DeleteFcn to only one void* typedef returned by a function, then the MATLAB user cannot directly call this deleter function by using that argument. MATLAB calls this function when the user calls the MATLAB delete function. The user can, however, directly call the deleter function by using any of the other void* typedef arguments.

For more information, see Lifetime Management of C++ Objects in MATLAB.

void* Return Types

Define Output Argument by Using typedef from Library

Define Output Argument from using Statement

Define Output Argument from New Type Name

Define Output Argument from Existing typedef

void* Input Argument Types

Define Input Argument as Fundamental Type

Define Input Argument as clib.array Type

Define Input Argument as C++ Class in Library

Define Input Argument as Existing void* typedef

void** Input Argument Types

Define Argument With void* typedef or using Statement From Library

Define Argument From New Type Name for void*

Define Argument From Existing void* typedef

MATLABType as Object of Class

Memory Management for void* and void** Arguments

Related Topics