# HG changeset patch
# User tomwalters
# Date 1266569511 0
# Node ID 3078854c634ab4bbd367fad038430a1af8e16be0
# Parent fcbf85ce59fb57b1691ea64e8319abb8b9fa1b04
- Renamed DeleteTarget and DeleteAllTargets to RemoveTarget and RemoveAllTargets in Module class
- Added a load of documentation
diff -r fcbf85ce59fb -r 3078854c634a doc/dox-mainpage.dox
--- a/doc/dox-mainpage.dox Thu Feb 18 21:12:41 2010 +0000
+++ b/doc/dox-mainpage.dox Fri Feb 19 08:51:51 2010 +0000
@@ -1,10 +1,15 @@
/*!
\mainpage AIM-C developer documentation
+\section intro_sec Introduction
AIM-C is a real-time version of the the auditory image model (AIM)
developed at the
Centre for the Neural Basis of Hearing.
+The main development site for AIM-C is at http://aimc.acousticscale.org/. The
+code is available at http://code.google.com/p/aimc/.
+
+\section design_sec Design
AIM-C uses a block-based processing scheme. A mono input signal is
split into short segments, which are sequentially 'pushed' through the
processing pipeline. The pipeline consists of a number of modules in a
@@ -15,25 +20,21 @@
segment, or 'frame', of an audio signal with multiple
channels. Modules generally take a frame (represented as a signal
bank) as input, and generate zero, one, or more signal bank frames as
-output. Each module is linked to a set of 'target' modules, to which
-they 'push' the frames which they generate. Each of these modules
+output. Each module maintains a list of 'target' modules, to which
+it 'pushes' the frames that it generates. Each module
performs processing on the output of the previous module, and in turn,
push the output that they produce to their targets.
-This feed-forward, tree-like system allows modules to retain the internal
-state required for processing
+This feed-forward, tree-like system allows modules to generate as many output
+frames as necessary for each input frame. It also allows for easy 'rewiring'
+of chains of modules. For example, a 'viewer' module could be temporarily
+added as a target of another module while the user was interested in seeing
+that module's output.
+Since each module is an instance of a class, it can retain the necessary state
+variables within the class between calls.
-
-
-You can browse the classes using the browser at the left, or
-select a page from the contents below.
-
-
-
-
-
-Coding style
+\section style_sec Coding style
For the most part, AIM-C now follows the
@@ -43,7 +44,4 @@
guide.
-
-
-
*/
diff -r fcbf85ce59fb -r 3078854c634a src/Modules/Features/ModuleGaussians.h
--- a/src/Modules/Features/ModuleGaussians.h Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Modules/Features/ModuleGaussians.h Fri Feb 19 08:51:51 2010 +0000
@@ -34,9 +34,6 @@
#include "Support/Parameters.h"
#include "Support/SignalBank.h"
-/*! \class ModuleGaussians "Modules/Features/ModuleGaussians.h"
- * \brief
- */
namespace aimc {
using std::vector;
class ModuleGaussians : public Module {
diff -r fcbf85ce59fb -r 3078854c634a src/Modules/Output/FileOutputHTK.h
--- a/src/Modules/Output/FileOutputHTK.h Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Modules/Output/FileOutputHTK.h Fri Feb 19 08:51:51 2010 +0000
@@ -18,7 +18,7 @@
/*!
* \file
- * \brief File output to HTK format class definition
+ * \brief File output to HTK format
*
* \author Tom Walters
* \author Willem van Engen
@@ -69,13 +69,6 @@
((((uint32_t) n) >> 8) & 0x0000FF00) | \
((((uint32_t) n) >> 24) & 0x000000FF) )
-/*!
- * \class FileOutputHTK "Output/FileOutputHTK.h"
- * \brief File output to HTK class
- *
- * This class gives a method for saving either a signal or a profile to HTK format.
- * \sa Signal, SignalBank
- */
namespace aimc {
class FileOutputHTK : public Module {
public:
diff -r fcbf85ce59fb -r 3078854c634a src/Modules/Strobes/ModuleParabola.h
--- a/src/Modules/Strobes/ModuleParabola.h Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Modules/Strobes/ModuleParabola.h Fri Feb 19 08:51:51 2010 +0000
@@ -34,10 +34,6 @@
#include "Support/Parameters.h"
#include "Support/SignalBank.h"
-/*!
- * \class ModuleParabola "Modules/SAI/ModuleParabola.h"
- * \brief SF 2003
- */
namespace aimc {
using std::vector;
class ModuleParabola : public Module {
diff -r fcbf85ce59fb -r 3078854c634a src/Support/Module.cc
--- a/src/Support/Module.cc Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Support/Module.cc Fri Feb 19 08:51:51 2010 +0000
@@ -109,13 +109,13 @@
return false;
}
-bool Module::DeleteTarget(Module* target_module) {
+bool Module::RemoveTarget(Module* target_module) {
if (targets_.erase(target_module) != 0)
return true;
return false;
}
-void Module::DeleteAllTargets() {
+void Module::RemoveAllTargets() {
targets_.clear();
}
diff -r fcbf85ce59fb -r 3078854c634a src/Support/Module.h
--- a/src/Support/Module.h Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Support/Module.h Fri Feb 19 08:51:51 2010 +0000
@@ -20,30 +20,6 @@
* \brief Base class for all AIM-C modules.
*/
-/*! The module construcor is called with a pointer to a set of Parameters.
- * In the constructor, the module sets the defaults for its various
- * parameters.
- * A module is initialized with a pointer to a valid SignalBank
- * (source modules can be initialized with the NULL pointer). After the
- * Initialize(SignalBank*) function has been called, a call to GetOutputBank()
- * returns a pointer to a SignalBank in which the results
- * of the module's processing will be placed. Modules can use the output_
- * SignalBank to store their output, or leave it uninitialized if they do not
- * produce an output.
- * At each call to Process(input), the module takes the
- * SignalBank 'input' (which must, unless otherwise specified, have the same
- * number of channels, sample rate, buffer size and centre frequencies as the
- * SignalBank which was passed to Initialize()), processes it, and places the
- * output in the internal SignalBank output_.
- * Modules can have an arbitrary number of unique targets. Each
- * completed output frame is 'pushed' to all of the targets of the module
- * in turn when PushOutput() is called. To achieve this, after each complete
- * output SignalBank is filled, the module calls the Process() function of
- * each of its targets in turn.
- * When Initialize() is first called. The module Initialize()s all of its
- * targets with its ouptut_ SignalBank, if it's output bank has been set up.
- */
-
/*! \author: Thomas Walters
* \date 2010/01/23
* \version \$Id: Module.h 4 2010-02-03 18:44:58Z tcw $
@@ -62,54 +38,125 @@
namespace aimc {
using std::set;
using std::string;
+
+/*! \brief Base class for all AIM-C modules.
+ *
+ * Module() is a base class, from which all AIM-C modules are derived.
+ * Classes deriving from module need to implement, at minimum, the pure
+ * virtual public function Module::Process() and the pure virtual private
+ * functions Module::InitializeInternal() and Module::ResetInternal().
+ * (Note: this is in contravention of
+ *
+ * this rule on inheritance in the Google style guide, but it is designed
+ * to make the implementation of modules as simple as possible.)
+ *
+ * The module constructor is called with a pointer to a set of Parameters.
+ * In the constructor, the module sets the defaults for its various
+ * parameters.
+ * A module is initialized with a reference to a valid SignalBank. After the
+ * Initialize(SignalBank*) function has been called, a call to GetOutputBank()
+ * returns a pointer to a SignalBank in which the results
+ * of the module's processing will be placed. Modules can use the output_
+ * SignalBank to store their output, or leave it uninitialized if they do not
+ * produce an output.
+ * At each call to Process(input), the module takes the
+ * SignalBank 'input' (which must, unless otherwise specified, have the same
+ * number of channels, sample rate, buffer size and centre frequencies as the
+ * SignalBank which was passed to Initialize()), processes it, and places the
+ * output in the internal SignalBank output_.
+ * Modules can have an arbitrary number of unique targets. Each
+ * completed output frame is 'pushed' to all of the targets of the module
+ * in turn when PushOutput() is called. To achieve this, after each complete
+ * output SignalBank is filled, the module calls the Process() function of
+ * each of its targets in turn.
+ * When Initialize() is first called. The module Initialize()s all of its
+ * targets with its ouptut_ SignalBank, if its output bank has been set up.
+ *
+ */
class Module {
public:
explicit Module(Parameters *parameters);
virtual ~Module();
- /* \brief Validate this module's output SignalBank, and initialize
+ /* \brief Initialize the module, including calling InitializeInternal().
+ * Validate this module's output SignalBank, and initialize
* any targets of the module if necessary.
* \param input Input SignalBank.
- * \param output true on success, false on failure.
+ * \return true on success, false on failure.
*
- * Note that in most instances when creating a new module, it is better to
- * simply implement the pure virtual function InitializeInternal(), rather
- * than refining a new Initialize. The only reason that Initialize() is made
- * virtual is to deal with the edge case of input modules which do not take
- * a SignalBank as input, but rather generate their own input.
+ * A call to Initialize() will first validate the input SignalBank passed to
+ * it. If this SignalBank is valid, then it will call the
+ * InitializeInternal() function of the child class; this will set up the
+ * child class, and may, if the module produces an output, initialize the
+ * member variable SignalBank output_. If output_ is initialized after the
+ * call to InitializeInternal(), the module will Initialize its targets with
+ * the output. In this way, it is possible to initialize an entire module
+ * tree with a single call to the Initialize() function of the root.
+ *
+ * This function is declared virtual in order to deal with the edge case of
+ * input modules which do not take a SignalBank as input, but rather
+ * generate their own input. In this case, it is better to be able to
+ * override the default Initialize function. When creating a new module, do
+ * not create a new version of Initialize uness you're sure you know what
+ * you're doing!
*/
virtual bool Initialize(const SignalBank &input);
- /*! \brief
+ /*! \brief Returns true if the module has been correctly initialized
+ * \return true if module has been initialized, false otherwise
*/
bool initialized() const;
/* \brief Add a target to this module. Whenever it generates a new
* output, this module will push its output to all its targets.
- * \param input Target module to add.
- * \param output true on success, false on failure.
+ * \param target_module Pointer to a target Module to add.
+ * \return true on success, false on failure.
+ *
+ * When a pointer is passed as a target to the module, the caller retains
+ * ownership of the module that it points to. The pointed-to module must
+ * continue to exist until it is deleted from the target list by a call
+ * to DeleteTarget() or DeleteAllTargets(), or the current module is
+ * destroyed. Bad things will happen if the Module pointed to is deleted
+ * and Initialize(), Reset() or Process() is subsequently called.
*/
bool AddTarget(Module* target_module);
- /*! \brief
+ /*! \brief Remove a previously added target module from the list of targets
+ * for this module.
+ * \param target_module Pointer to the module to remove. This must be a
+ * pointer that was previously passed to AddTarget()
+ * \return true on success, false on failure.
*/
- bool DeleteTarget(Module* target_module);
+ bool RemoveTarget(Module* target_module);
- /*! \brief
+ /*! \brief Remove all previously added target modules from the list of
+ * targets for this module.
*/
- void DeleteAllTargets();
+ void RemoveAllTargets();
- /*! \brief Process a buffer
+ /*! \brief Process a buffer.
+ * \param input SignalBank of the form which was passed to Initialize()
+ *
+ * Process is called once for each input SignalBank. When implemented in
+ * classes inheriting from aimc::Module, P
+ * this SignalBank contains the (read-only) input to the module. It is
+ * expected that the input SignalBank will have the same number of channels,
+ * buffer length and sample rate as the SignalBank passed to Initialize.
*/
virtual void Process(const SignalBank &input) = 0;
/*! \brief Reset the internal state of this module and all its children to
* their initial state.
+ *
+ * Like a call to Initialize() will cause all target modules to be
+ * initialized, a call to Reset() will cause all target modules to be reset.
*/
void Reset();
- /*! \brief
+ /*! \brief Return a pointer to the output SignalBank_ for this class.
+ * \return pointer to the SignalBank that this module uses to store its
+ * output.
*/
const SignalBank* GetOutputBank() const;
diff -r fcbf85ce59fb -r 3078854c634a src/Support/StrobeList.h
--- a/src/Support/StrobeList.h Thu Feb 18 21:12:41 2010 +0000
+++ b/src/Support/StrobeList.h Fri Feb 19 08:51:51 2010 +0000
@@ -20,7 +20,7 @@
* \file
* \brief Modifiable List of Strobe Points - helper for SAI generation
*
- * \author Tom Walters
+ * \author Tom Walters
* \date created 2007/08/22
* \version \$Id: StrobeList.h 1 2010-02-02 11:04:50Z tcw $
*/
@@ -44,11 +44,6 @@
}
};
-/*!
- * \class Signal "Support/StrobeList.h"
- * \brief Modifiable List of Strobe Points, which must be ordered
- *
- */
class StrobeList {
public:
/*! \brief Create a new strobe list