name: FtrBuffer
synopsis:

>     g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_sp.a

>     #include <FtrBuffer.h>

>     FtrBuffer();
>     FtrBuffer(const FtrBuffer& arg);
>     boolean eq(const FtrBuffer& arg) const;
>     boolean setCoefName(const String& arg);
>     long getLength(const String& cname) const;

quick start:

>     FtrBuffer buf;
>     String param1(L"some_features");
>     buf.addOrInitBuffer(param1, 1);
>     buf.setLeftoverSamps(0);

description:
The FtrBuffer class is used by the AudioFrontEnd class to manage the internal buffering of data between Algorithm objects. For example, when the Filter algorithm needs to be applied in the signal flow graph, the AudioFrontEnd will read the inputs from the FtrBuffer, call the compute method of the algorithm, then write the output back to the FtrBuffer. This is another class that primarily exists to facilitate the front end processing software, and does not need to be used directly by application programmers.
dependencies:

- HashTable
- String
- Vector
- CircularBuffer
- AlgorithmData
- Long
- MemoryManager

public constants:

- define the class name:

      static const String CLASS_NAME = L"FtrBuffer";

- define i/o related constants:

      static const String PARAM_HASH = L"hash";

      static const String PARAM_LENGTH = L"length";

      static const String PARAM_FRAME_INDEX = L"frame_index";

      static const String PARAM_LAST_INDEX = L"last_index";

      static const String PARAM_COEF_NAME = L"coef_name";

      static const String PARAM_LEFTOVER = L"leftover";

- define default value(s) of the class data:

      static const float ALL_TIME = -1;

      static const float DEF_END_TIME = ALL_TIME;

      static const float DEF_CONTEXT_WINDOW = ALL_TIME;

      static const double DEF_FRAME_DURATION = 0.01;

- define default argument(s):

      static const long DEF_COEF_BUF_CAPACITY = 512;

error codes:

- general error codes:

      static const long ERR = 80300;

protected data:

- circular buffer for holding coefficients:

      HashTable<String, Vector< CircularBuffer<AlgorithmData> > > hash_d;

- required frames for each coefficient:

      HashTable<String, Long> length_d;

- frame references for circular buffer:

      Long frame_index_d;

      Long last_index_d;

- coefficient name:

      String coef_name_d;

- number of samples in the last frame:

      Long leftover_samps_d;

- static debug level:

      static Integral::DEBUG debug_level_d;

- static memory manager:

      static MemoryManager mgr_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods:

      boolean debug(const unichar* message) const;

      static boolean setDebug(Integral::DEBUG debug_level);

- destructor/constructor(s):

      ~FtrBuffer();

      FtrBuffer();

      FtrBuffer(const FtrBuffer& arg);

- assign methods:

      boolean assign(const FtrBuffer& arg);

- i/o methods:

      long sofSize() const;

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

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

      boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

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

- equality methods:

      boolean eq(const FtrBuffer& arg) const;

- memory management methods:

      static void* operator new(size_t size);

      static void* operator new[](size_t size);

      static void operator delete(void* ptr);

      static void operator delete[](void* ptr);

      static boolean setGrowSize(long grow_size);

      boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

- set methods:

      boolean setCoefName(const String& arg);

      boolean setFrameIndex(long arg);

      boolean setLastIndex(long arg);

      boolean setLeftoverSamps(long arg);

- get methods:

      const String& getCoefName() const;

      long getFrameIndex() const;

      long getLastIndex() const;

      long getLeftoverSamps() const;

      long getLength(const String& cname) const;

      const HashTable<String, Long>& getLength() const;

- length access and management methods:

      boolean addOrinitLength(const String& cname, long len = 0);

      boolean setLengthToMax(const String& cname, long new_len);

- buffer access and management methods:

      boolean resetBuffer();

      boolean contains(const String& arg) const;

      Vector< CircularBuffer<AlgorithmData> >& getBuffer();

      Vector< CircularBuffer<AlgorithmData> >& getBuffer(const String& cname);

      const Vector< CircularBuffer<AlgorithmData> >& getBuffer() const;

      const Vector< CircularBuffer<AlgorithmData> >& getBuffer(const String& cname) const;

      AlgorithmData& getData(long ctag, long index, const String& cname);

      const AlgorithmData& getData(long ctag, long index, const String& cname);

      boolean addOrInitBuffer(const String& cname, long num_chan, long buf_cap = DEF_COEF_BUF_CAPACITY);

      boolean ensureChannels(const String& cname, long num_chan);

      boolean ensureBufferTrailingPad(const String& cname, long req_pad);

      boolean ensureBufferLeadingPad(const String& cname, long req_pad);

      boolean advanceRead();

      boolean advanceCurr();

private methods:

- none.

examples:

- This example shows how to use FtrBuffer:

      FtrBuffer buf;
      String param1(L"some_features");
      String param2(L"other_features");

      // single channel data
      //
      buf.addOrInitBuffer(param1);

      // multi-channel data
      //
      buf.addOrInitBuffer(param2, 2);

      // add some data to the circular buffer
      //
      AlgorithmData a;
      buf.getBuffer(param1)(0).append(a);

      // add some data to both channels of the other buffer
      //
      buf.getBuffer(param2)(0).append(a);
      buf.getBuffer(param2)(1).append(a);

notes:

- none.