How to use C library created by MATLAB Coder codegen in C program with emxArray arguments?

Question

The C function (C static library) created by codegen takes an input argument of type const emxArray_uint32_T and return values of type emxArray_struct_T. As the type suggests, input is an array of uint32 and output is an array of struct.

I'm not sure how to use this function in my C program. For the input, should I declare an array of type uint32_T or use the type emxArray_uint32_T ? For the output, because I don't know the size of the output array, how to declare the array of struct to receive the return values from the function?

I put the question in MATLAB answers but have not luck..

Thanks!

Loculus

Answer 1

If you've used C++, the emxArray data types are like generated C equivalents of std::vector. Namely, this is how the generated code represents dynamically allocated arrays. They store data and size pointers as well as a few other details.

If you look in the directory where you generated code you should find a file named <functionName>_emxAPI.h. This file declares some utility functions which make constructing and destroying emxArray values simpler. Using them to create emxArray values ensures that all of the fields are properly initialized and insulates your code from any possible changes to the emxArray type.

In an example I made which takes an array of uint32 values and also returns such an array, I see the following functions:

extern emxArray_uint32_T *emxCreateWrapperND_uint32_T(unsigned int *data, int
                                                      numDimensions, int *size);
extern emxArray_uint32_T *emxCreateWrapper_uint32_T(unsigned int *data, int rows,
                                                    int cols);
extern emxArray_uint32_T *emxCreateND_uint32_T(int numDimensions, int *size);
extern emxArray_uint32_T *emxCreate_uint32_T(int rows, int cols);
extern void emxDestroyArray_uint32_T(emxArray_uint32_T *emxArray);

The first four functions can be used to create emxArray values in different situations.

The first pair, i.e. emxCreateWrapper_uint32_T, emxCreateWrapperND_uint32_T, can be used to create a uint32 emxArray with the specified number of dimensions and sizes from existing data. So if you already have the input data allocated in some memory, these functions wrap that data up into an emxArray of the specified size without allocating extra memory for your data.

/* Create a 10-by-10 C array of uint32 values and wrap an emxArray around it */
uint32_T x[100];
emxArray *pEmx = NULL;
int k = 0;
for (k = 0; k < 100; k++) {
    x[k] = (uint32_T) k;
}

pEmx = emxCreateWrapper_uint32_T(x, 10, 10);

/* Use pEmx here*/

/* Deallocate any memory allocated in pEmx. */
/* This DOES NOT free pEmx->data because the "wrapper" function was used */
emxDestroyArray_uint32_T(pEmx);

The second pair, i.e. emxCreate_uint32_T, emxCreateND_uint32_T, also create emxArray values. However, they also heap allocate storage for the data field of the emxArray. This memory will be large enough to hold the number of elements specified in their respective size arguments After calling these, you will need to populate the data stored in the data field of the returned emxArray struct:

/* Allocate a 10-by-10 uint32 emxArray and fill the values */
int k = 0;
emxArray *pEmx = emxCreate_uint32_T(10, 10);
for (k = 0; k < 100; ++k) {
    pEmx->data[k] = (uint32_T) k;
}

/* Use pEmx here*/

/* Deallocate any memory allocated in pEmx. */
/* This DOES free pEmx->data */
emxDestroyArray_uint32_T(pEmx);

The last, emxDestroyArray_uint32_T, will be used to destroy the array and deallocate any memory allocated by the previous methods.

Finally, to capture your output, you could use emxCreate_struct_T or emxCreateND_struct_T to create an empty emxArray of struct_T values with the proper number of dimensions by passing 0 for one or more sizes where appropriate. The generated code will allocate enough memory to hold the resulting data in your output emxArray at runtime. You can then check the size field of this output emxArray to view the sizes of the dimensions of the data field and extract the data as you wish.

The documentation for using emxArray arguments is available here.

Kester

I did not see what to do with dynamically sized return values as I didn't have wrappers for those but this worked for me: emxArray_real_T *fixes; emxInitArray_real_T(&fixes, 2); (and later) emxDestroyArray_real_T(fixes); – Redfin

Answer 2

You need to use emxArray_uint32_T and emxArray_struct_T. All of the MATLAB Coder defined datatypes that the code uses (and you need to use) are defined in the YourLibName_types.h header file.

Torres

Thanks Phil. I check the header file, both emxArray_uint32_T and emxArray_struct_T are structs, each with several fields (the input array itself, size of the array etc...), does that mean I need to assign values to these fields (I mean besides the input array itself) before using the whole struct as the function argument? – Loculus

Yes, you need to define all data required by the function. – Torres