Working with Structure Arguments

Structure Argument Requirements

When you pass a MATLAB® structure to an external library function:

  • Every MATLAB field name must match a field name in the library structure definition. Field names are case sensitive.

  • MATLAB structures cannot contain fields that are not in the library structure definition.

  • If a MATLAB structure contains fewer fields than defined in the library structure, MATLAB sets undefined fields to zero.

You do not need to match the data types of numeric fields. The calllib function converts to the correct numeric type.

Finding Structure Field Names

To determine the name and data type of structure fields, you can:

  • Consult the library documentation.

  • Look at the structure definition in the library header file.

  • Use the libstruct function. For an example, see Display Structure Field Names.

Strategies for Passing Structures

MATLAB automatically converts a structure to the library definition for that structure type. For most cases, such as working with small structures, this works fine. For an example, see Add Values of Fields in Structure.

However, when working with repeated calls that pass one or more large structures, it might be to your advantage to convert the structure manually before making any calls to external functions. In this way, you save processing time by converting the structure data only once at the start rather than at each function call. You can also save memory if the fields of the converted structure take up less space than the original MATLAB structure.

To manually convert, call the libstruct function to create a libstruct object. Although it is an object, it behaves like a MATLAB structure. The fields of the object are derived from an externally-specified structure type. For an example, see Preconvert MATLAB Structure Before Adding Values.

Was this topic helpful?