name: AlgorithmBase

synopsis:

This class is never used directly. It is inherited by all Algorithms
classes.  Users will mainly interact with it indirectly by using some of
the enumerations included in the class definition, and its protected
data, which plays an important part in the control structure for all
Algorithm classes.  AlgorithmBase, like many of the classes named
Algorithm, play an important role in the signal processing tools found
in the Signal Processing library.

quick start:

Filter filt;
filt.setSampleFrequency(16000.0);
filt.setFrameDuration(0.020);

description:

The AlgorithmBase class is inherited by all Algorithm classes, and contains some information (data and methods) expected to be common to all such classes. For example, variables that hold debugging information, error codes, initialization status, sample frequency, frame duration, and I/O are stored in AlgorithmBase. Several important enumerations are also defined here.

However, this information is never accessed by instantiating an AlgorithmBase object directly. Rather, this information is accessed via the inherited class. A typical case is shown in the quick start example above. Correlation is an Algorithm class that inherits AlgorithmBase. The set methods invoked above are available through inheritance. The data members that store this information are contained in AlgorithmBase.

AlgorithmBase serves two important functions. First, it defines the interface contract that all Algorithm classes must adhere to in order that they can be used by transform_builder. Second, it centralizes useful data common to all algorithms, such as sample frequency and frame duration.

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"AlgorithmBase";

define an enumeration for the data format: for some classes, such as filter, we must know whether the the algorithm is frame-based or sample-based, so that we output the correct number of samples.
```
enum CMODE { FRAME_BASED = 0, SAMPLE_BASED, DEF_CMODE = FRAME_BASED };
```
define an enumeration for cross-frame processing: many of the algorithms share a property that they can operate only on data within the current frame (FRAME_INTERNAL), data across several frames (CROSS_FRAME), or produce one result per file (ACCUMULATE).
```
enum DMODE { FRAME_INTERNAL = 0, CROSS_FRAME, ACCUMULATE, DEF_DMODE = FRAME_INTERNAL };
```

define static NameMap objects:

static const NameMap CMODE_MAP = L"FRAME_INTERNAL, CROSS_FRAME, ACCUMULATE";

static const NameMap DMODE_MAP = L"FRAME_BASED, SAMPLE_BASED";

define i/o related variables:

const String AlgorithmBase::PARAM_DBGL(L"debug_level");

define the default values and arguments: these are some useful signal processing constants common to all algorithms.

static const float DEF_SAMPLE_FREQUENCY = 8000;

static const float DEF_FRAME_DURATION = 0.01;

static const float DEF_SIGNAL_DURATION = 1.0;

static const float DEF_FRAME_INDEX = -1;

define constants related to multichannel signals:

static const long DEF_NUM_CHANNELS = 1;

static const long DEF_CHANNEL_INDEX = 0;

define the default values and arguments: the constants are used to control how much history and lookahead an algorithm needs.
```
static const long DEF_LEADING_PAD = 0;
```
```
static const long DEF_TRAILING_PAD = 0;
```

error codes:

error codes:

static const long ERR = 70000;

static const long ERR_UNKALG = 70001;

static const long ERR_UNKIMP = 70002;

static const long ERR_UNKTYP = 70003;

static const long ERR_UNSUPA = 70004;

static const long ERR_UNSUPI = 70005;

static const long ERR_UNSUPM = 70006;

static const long ERR_INSUFD = 70007;

static const long ERR_ORDER = 70008;

static const long ERR_UNCTYP = 70009;

static const long ERR_COMPF = 70010;

protected data:

debugging parameters:
```
DebugLevel debug_level_d;
```
initialization flag:
```
boolean is_valid_d;
```
computational mode:
```
CMODE cmode_d;
```
data processing mode:
```
DMODE dmode_d;
```

float sample_freq_d;

float frame_dur_d;

float signal_duration_d;

long leftover_samps_d;

long frame_index_d;

long num_channels_d;

i/o-related parameters (amount of data needed, offset with respect to the current time):
```
long num_elements_d;
```
```
long offset_d;
```

required public methods:

static methods:

static const SysString& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods:

boolean setDebug(Integral::DEBUG level);

boolean debug(const unichar* message) const;

destructor/constructor(s):

~AlgorithmBase();

AlgorithmBase();

AlgorithmBase(const AlgorithmBase& arg);

assign methods:

virtual boolean assign(const AlgorithmBase& arg);

i/o methods:

virtual long sofSize() const = 0;

virtual boolean read(Sof& sof, long tag, const String& name) = 0;

virtual boolean write(Sof& sof, long tag, const String& name) const = 0;

virtual boolean readData(Sof& sof, const String& pname, long size, boolean param, boolean nested) = 0;

virtual boolean writeData(Sof& sof, const String& pname) const = 0;

equality methods:

virtual boolean eq(const AlgorithmBase& arg) const;

memory management methods: new and delete methods are omitted since only the derived classes will be used
```
virtual boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);
```

class-specific public methods:

set methods:

virtual boolean setComputeMode(CMODE format);

virtual boolean setDataMode(DMODE mode);

virtual boolean setSampleFrequency(float sf);

virtual boolean setFrameDuration(float fdur);

virtual boolean setSignalDuration(float fdur);

virtual boolean setLeftoverSamps(long samps);

virtual boolean setFrameIndex(long index);

virtual boolean setNumChannels(long num_channels);

get methods:

CMODE getComputeMode() const;

DMODE getDataMode() const;

float getSampleFrequency() const;

float getFrameDuration() const;

float getSignalDuration() const;

virtual long getLeftoverSamps();

long getFrameIndex() const;

long getNumChannels() const;

boolean isValid() const;

AlgorithmBase interface contract methods:

virtual const String& className() const;

virtual boolean init();

virtual boolean apply(Vector& output, const Vector< CircularBuffer >& input);

virtual long getLeadingPad() const;

virtual long getTrailingPad() const;

virtual CMODE getOutputMode() const;

virtual boolean setParser(SofParser* parser);

boolean displayStart(const AlgorithmBase* algo);

boolean displayFinish(const AlgorithmBase* algo);

boolean displayChannel(long channel);

boolean display(const TData0& output_a, const TData1& input_a, const String& algo_name);

private methods:

none.

examples:

Since this class is never called directly, there are no examples.

notes:

AlgorithmBase is used by all Algorithm classes, and interfaces to higher-level classes such as Cepstrum, Calculus etc. through classes such as Recipe and AudioFrontEnd.
The internal variables cmode_d and dmode_d were moved into this class since it was decided that all Algorithm classes should support these choices. The variable cmode_d refers to whether the algorithm uses data within the current frame, or data outside the frame. The variable dmode_d refers to the type of data processing: sample-based processing (used by Filter) versus frame-based processing (used by most classes including Cepstrum).