libpointer (External Interfaces Reference)

Create pointer object for use with external libraries

Syntax

p = libpointer
p = libpointer('type')
p = libpointer('type', value)

Description

p = libpointer returns an empty (void) pointer.

p = libpointer('type') returns an empty pointer that contains a reference to the specified data type. This type can be any MATLAB numeric type, or a structure or enumerated type defined in an external library that has been loaded into MATLAB with the loadlibrary function. For valid types, see the table under Primitive Types in the MATLAB documentation.

p = libpointer('type', value) returns a pointer to the specified data type and initialized to the value supplied.

Examples

This example passes an int16 pointer to a function that multiplies each value in a matrix by its index. The function multiplyShort is defined in the MATLAB sample shared library, shrlibsample.

Here is the C function:

void multiplyShort(short *x, int size)
{
    int i;
    for (i = 0; i < size; i++)
    *x++ *= i;
}

Load the shrlibsample library. Create the matrix, v, and also a pointer to it, pv:

addpath([matlabroot '\extern\examples\shrlib'])
loadlibrary shrlibsample shrlibsample.h

v = [4 6 8; 7 5 3];

pv = libpointer('int16Ptr', v);
get(pv, 'Value')
ans =
     4     6     8
     7     5     3

Now call the C function in the library, passing the pointer to v. If you were to pass a copy of v, the results would be lost once the function terminates. Passing a pointer to v enables you to get back the results:

calllib('shrlibsample', 'multiplyShort', pv, 6);
get(pv, 'Value')
ans =
     0    12    32
     7    15    15

unloadlibrary shrlibsample

Note In most cases, you can pass by value and MATLAB will automatically convert the argument to a pointer for you. See Creating References, in the MATLAB documentation for more information.

libisloaded libstruct