Pointer Arguments in C Functions
Many functions in external libraries pass arguments by reference. When you pass by reference, you pass a pointer to the value. In the function signature, pointer arguments have names ending in and . Although MATLAB® does not support passing by reference, you can create a MATLAB argument, called a lib.pointer object, that is compatible with a C pointer. This object is an instance of the MATLAB class.
Often, you can simply pass a MATLAB variable (passing an argument by value), even when the signature for that function declares the argument to be a pointer. There are times, however, when it is useful to pass a .
You want to modify the data in the input arguments.
You are passing large amounts of data, and you want to control when MATLAB makes copies of the data.
The library stores and uses the pointer so you want the MATLAB function to control the lifetime of the object.
Put String into Void Pointer
C represents characters as 8-bit integers. To use a MATLAB character array as an input argument, convert the string to the proper type and create a . For example:
The syntax creates the null-terminated string required by the C function. To read the string, and verify the pointer type, enter:
MATLAB automatically converts an argument passed by value into an argument passed by reference when the external function prototype defines the argument as a pointer. Call a function that takes a to a string as an input argument using the following syntax.
Although MATLAB converts the argument from a value to a pointer, it must be of the correct type.
Memory Allocation for External Library
In general, MATLAB passes a valid memory address each time you pass a variable to a library function. Use a object in cases where the library stores the pointer and accesses the buffer over time. In these cases, ensure that MATLAB has control over the lifetime of the buffer and prevent copies of the data from being made. The following pseudo-code is an example of asynchronous data acquisition that shows how to use a in this situation.
Suppose an external library has the following functions:
where is declared as follows:
First, create a to an array of 99 points:
Then, begin acquiring data and wait in a loop until it is done:
The following statement reads the data in the buffer:
When the library is done with the buffer, clear the MATLAB variable:
This example shows how to write a MEX file to call a C function, , in MATLAB® using a MATLAB matrix. You can use these same C statements in a C++ application.
multiplies a 1xn matrix, , by a scalar value, , and returns the results in array, .
Create Source File
Open MATLAB Editor, create a file, and document the MEX file with the following information.
Add the C/C++ header file, , containing the MATLAB API function declarations.
Save the file on your MATLAB path, for example, in , and name it . The name of your MEX file is .
Create Gateway Routine
Every C program has a function. MATLAB uses the gateway routine, , as the entry point to the function. Add the following code.
This table describes the input parameters for .
|Number of output (left-side) arguments, or the size of the array.|
|Array of output arguments.|
|Number of input (right-side) arguments, or the size of the array.|
|Array of input arguments.|
Verify MEX File Input and Output Parameters
Verify the number of MEX file input and output arguments using the and arguments.
To check for two input arguments, and , use this code.
Use this code to check for one output argument, the product .
Verify the argument types using the and arguments. This code validates that , represented by , is a scalar.
This code validates that , represented by , is type .
Validate that is a row vector.
Create Computational Routine
Add the code. This function is your computational routine, the source code that performs the functionality you want to use in MATLAB.
A computational routine is optional. Alternatively, you can place the code within the function block.
Write Code for Cross-Platform Flexibility
MATLAB provides a preprocessor macro, , that represents size values for integers, based on the platform. The computational routine declares the size of the array as . Replace the declaration for variables and with .
Declare Variables for Computational Routine
Put the following variable declarations in .
Declare variables for the input arguments.double multiplier; /* input scalar */ double *inMatrix; /* 1xN input matrix */
Declare for the size of the input matrix.mwSize ncols; /* size of matrix */
Declare the output argument, .double *outMatrix; /* output matrix */
Later you assign the arguments to these variables.
Read Input Data
To read the scalar input, use the function.
Use the function to point to the input matrix data.
Use the function to get the size of the matrix.
Prepare Output Data
To create the output argument, , use the function.
Use the function to assign the argument to
Pass the arguments to .
View Complete Source File
Compare your source file with , located in . Open the file in the editor.
Build Binary MEX File
At the MATLAB command prompt, build the binary MEX file.
Test the MEX File
Validate MEX File Input Arguments
It is good practice to validate the type of a MATLAB variable before calling a MEX file. To test the input variable, , and convert it to , if necessary, use this code.
| | | | |