AUX Library Reference Manual
AUX Library is a C library that enables researchers to build their own applications
utilizing AUX. This tool contains the modules for the analysis of input string and for
generation of actual signals.
The library has the following functions:
AUXNew............................................................................................................................... 2
AUXEval ............................................................................................................................... 3
AUXPlay ............................................................................................................................... 5
AUXWavwrite....................................................................................................................... 6
AUXGetErrMsg .................................................................................................................... 7
AUXGetInfo .......................................................................................................................... 8
AUXDelete ........................................................................................................................... 9
AUXNew
creates a new environment for AUX processing.
Syntax
#include “AUXLib.h”
int AUXNew (const int sample_rate, const char *wavepath, const
char *auxpath, , const char *datapath);
Parameters
int sample_rate
The default sampling rate for the new environment.
char *wavepath
The default directory to search for wave files. Can be NULL when unused.
char *auxpath
The default directories to search for aux files (user-defined functions). Multiple
directories can be specified, separated by semicolons. Can be NULL when unused.
char *datapath
The default directory to search for data files of file( ) AUX function. Can be NULL
when unused.
Retrun Value
If the function succeeds, it returns zero or a positive integer that specifies the
handle to the AUX environment created.
If the function fails, the return value is a negative integer. To get the error message,
call AUXGetErrMsg().
Remarks
This library is designed to handle multiple independent scripts. Each independent
script has its own environment, i.e. set of variables and user-defined functions,
which is represented by a handle.
When the AUX environment is no longer in use, AUXDelete() should be called in
order to prevent memory leaks.
AUXEval
parses and executes the input string
Syntax
#include “AUXLib.h”
int AUXEval (const int hAUX, const char *strIn, double **buffer,
int *length);
Parameters
int hAUX
The handle to the AUX environment created by AUXNew().
char *strIn
The input string to parse and execute.
The input string may contain several assignment expressions delimited by carriage
return (CR) and/or line feed (LF) for variable definitions.
The result of last expression evaluated will be the resulting signal of this function
call.
The values of variables and user-defined functions are kept in the internal AUX
environment associated with the handle, and can be re-used in the subsequent
calls to AUXEval with the same hAUX.
double **buffer [out]
int *length [out]
A pointer to receive the address of the internal C double array, and
a pointer to an int, respectively.
They can be null (‘\0’), when the resulting signal is not of interest. (e.g. The script
has only variable definitions.)
Upon successful execution, buffer gets the pointer to the internal buffer which
has the resulting signal, length gets the number of samples of the signal;
If the signal has multiple channels, the samples of the subsequent channel follow
the last sample of the preceding channel, making the total size of the buffer
[number_of_channels * length].
Retrun Value
If the function succeeds, it returns the number of channels generated by the script,
zero for an empty result.
If the function fails, the return value is a negative integer. To get the error message,
call AUXGetErrMsg().
AUXPlay
plays the resulting sound of the last AUXEval().
Syntax
#include “AUXLib.h”
int AUXPlay (const int hAUX, const int DevID);
Parameters
int hAUX
The handle to the AUX environment created by AUXNew().
int DevID
The ID of the device to play the sound
(0-based index)
Retrun Value
If the function succeeds, the return value is 1.
If the function fails, the return value is 0. To get the error message, call
AUXGetErrMsg().
AUXWavwrite
writes the resulting sound of the last AUXEval(), to a .wav file.
Syntax
#include “AUXLib.h”
int AUXWavwrite (const int hAUX, const char *filename);
Parameters
int hAUX
The handle to the AUX environment created by AUXNew().
char *filename
The name of the wav file to generate.
Retrun Value
If the function succeeds, the return value is 1.
If the function fails, the return value is 0. To get the error message, call
AUXGetErrMsg().
AUXGetErrMsg
returns the last error message.
Syntax
#include “AUXLib.h”
const char *AUXGetErrMsg (void);
Parameters
None.
Retrun Value
The return value is the pointer to the internal string buffer for the last error message.
AUXGetInfo
Retrieves various internal properties of an AUX environment
Sytax
#include “AUXLib.h”
int AUXGetInfo (const int hAUX, const char *name, void *output);
Parameters
int hAUX
The handle to the AUX environment created by AUXNew().
char *name
The name of the property to retrieve
void *output [out]
A pointer to receive the value.
Retrun Value
If the function succeeds, the return value is 1.
If the function fails, the return value is 0. To get the error message, call
AUXGetErrMsg().
Remarks
Property name
Actual type of output
wavepath
char *
auxpath
char *
datapath
char *
fs
int *
AUXDelete
destroys the AUX environment and releases all the memory associated with the
hAUX supplied.
Syntax
#include “AUXLib.h”
void AUXDelete (const int hAUX);
Parameters
int hAUX
the handle to the AUX environment created by AUXNew().
Retrun Value
None
Remarks
When the AUX environment is no longer in use, AUXDelete() should be called in
order to prevent memory leaks.
For example, the AUX GenView program or something similar can be made easily with
AUX Library. To generate a signal, the AUXEval function can be called twice: first with
the string input from the “Variable Definition” edit box, and subsequently with the string
from the “Signal Definition” edit box.
Because the library is provided in a ANSI-C format, this can also be used in other
language environment that provides an interface to C API calls; thus, a wide range of
programmers (not necessary C developers) who work in various programming
environments can benefit from this, such as Visual Basic, .NET, and MATLAB (as in the
mex format).