Functions

Functions in the MaxMAL Library are divided into 2 main categories, General Functions and functions performing calculations or data processing.  the General Function are used to get or set information in the MaxMAL LIbrary.  The data processing and calculation functions are divided into sub categories.

Function call syntax have 2 main formats

Format 1 -  Return a number of type REAL

real-number = MAL.Function( input-array, optional point, channel, dimension and frame specifications )

Format 2 - Return a reference to output array

array-reference = MAL.Function( output array, input-arrays, optional point, channel, dimension and frame specifications )

By returning a reference to an output array, the functions can be used as an input to other MaxMAL function calls.  You may also omit or specify NULL as the output array.  In this case, an output array of approproate dimensions and length is dynamically created.  These arrays always contains a single point or channel and epending on the function and the input arrays data format the output array can be 1D, 2D or 3D.

In general, when a function contains only one output array parameter or one output and one input array and there are no parameter ambiguities, the output array can be omitted.  In all other cases, you need to specify the output parameter as NULL in order for the function to dynamically allocate the output array.  Any optional output array parameters are enclosed with a pair of square brackets.  For example;

[BYREF arr_out  AS ARRAY]

Any option input arrays and parameters are also marked with a pair of square brackets as well as their default values.  For example, the Vector Length function can have only one input parameter, the 2D/3D data to calculate the vector length from.

ref_arr_out = MAL.VectorLength( [BYREF arr_out      AS ARRAY],

                                BYREF arr_in       AS ARRAY,

                               [BYVAL nPoint       AS INTEGER=ML_ALL],

                               [BYVAL nFrameOffset AS INTEGER=0] ) AS REFERENCE

When using dynamic array allocation, it's a good idea to turn on the automatic garbage collection.  Use OPTION GARBAGE ON for to turn on the automatic garbage collection.

Array Formats

Input and Output arrays are declared as

DIM array( Frames, Points, 2 )   AS REAL   ' 2D Data

DIM array( Frames, Points, 3 )   AS REAL   ' 3D Data

DIM array( Frames, Channels, 1 ) AS REAL   ' 1D Data

DIM array( Frames, Channels )    AS REAL   ' 1D Data

When there only one point or channel, arrays may be declared as

DIM array( Frames, 2 ) AS REAL   ' 2D Data

DIM array( Frames, 3 ) AS REAL   ' 3D Data

DIM array( Frames, 1 ) AS REAL   ' 1D Data

DIM array( Frames )    AS REAL   ' 1D Data

These are the formats that are used when single point/channel output arrays are dynamically created.  See Arrays for more information.

Specifying Points, Channels, Dimension and Frames

There are 2 ways that you can specify point/channels, dimensions and frames.  When input are calling for 2D or 3D data, you specify the points to process as Point numbers always starting at number 1.  You can also specify a frame offset.  The defaults are to process all points and frames.  The function can also accept point and frame ranges specified by using PTS and FRS.  For example;

ref_arr_out = MAL.VectorLength( [BYREF arr_out      AS ARRAY],

                                BYREF arr_in       AS ARRAY,

                               [BYVAL nPoint       AS INTEGER=ML_ALL],

                               [BYVAL nFrameOffset AS INTEGER=0] ) AS REFERENCE

In the case when you can specify the data dimension as the input or output, the functions accept the array indexes as a Vector Index Array (VIXA).  You the VIX function.  For Example;

ref_arr_out = V1D( BYREF arr_out      AS ARRAY,

                  BYREF arr_in       AS ARRAY,

                  BYVAL vixa_in      AS INTEGER,

                 [BYVAL nFrames      AS INTEGER=ML_ALL] ) AS REFERENCE

Using this format, you can select any part of a 1D, 2D or 3D array.