tomwalters@0: // Copyright 2010, Thomas Walters
tomwalters@0: //
tomwalters@0: // AIM-C: A C++ implementation of the Auditory Image Model
tomwalters@0: // http://www.acousticscale.org/AIMC
tomwalters@0: //
tomwalters@0: // This program is free software: you can redistribute it and/or modify
tomwalters@0: // it under the terms of the GNU General Public License as published by
tomwalters@0: // the Free Software Foundation, either version 3 of the License, or
tomwalters@0: // (at your option) any later version.
tomwalters@0: //
tomwalters@0: // This program is distributed in the hope that it will be useful,
tomwalters@0: // but WITHOUT ANY WARRANTY; without even the implied warranty of
tomwalters@0: // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
tomwalters@0: // GNU General Public License for more details.
tomwalters@0: //
tomwalters@0: // You should have received a copy of the GNU General Public License
tomwalters@0: // along with this program.  If not, see <http://www.gnu.org/licenses/>.
tomwalters@0: 
tomwalters@0: /*! \file
tomwalters@0:  *  \brief Base class for all AIM-C modules.
tomwalters@0:  */
tomwalters@0: 
tomwalters@0: /*! \author: Thomas Walters <tom@acousticscale.org>
tomwalters@0:  *  \date 2010/01/23
tomwalters@23:  *  \version \$Id$
tomwalters@0:  */
tomwalters@0: 
tomwalters@11: #ifndef AIMC_SUPPORT_MODULE_H_
tomwalters@11: #define AIMC_SUPPORT_MODULE_H_
tomwalters@0: 
tomwalters@0: #include <set>
tomwalters@0: #include <string>
tomwalters@0: 
tomwalters@0: #include "Support/Common.h"
tomwalters@0: #include "Support/Parameters.h"
tomwalters@0: #include "Support/SignalBank.h"
tomwalters@0: 
tomwalters@0: namespace aimc {
tomwalters@0: using std::set;
tomwalters@0: using std::string;
tomwalters@9: 
tomwalters@9: /*! \brief Base class for all AIM-C modules.
tomwalters@9:  *
tomwalters@9:  * Module() is a base class, from which all AIM-C modules are derived. 
tomwalters@9:  * Classes deriving from module need to implement, at minimum, the pure
tomwalters@9:  * virtual public function Module::Process() and the pure virtual private 
tomwalters@9:  * functions Module::InitializeInternal() and Module::ResetInternal().
tomwalters@9:  * (Note: this is in contravention of 
tomwalters@9:  * <a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Inheritance#Inheritance">
tomwalters@9:  * this rule on inheritance</a> in the Google style guide, but it is designed 
tomwalters@9:  * to make the implementation of modules as simple as possible.)
tomwalters@9:  * 
tomwalters@9:  * The module constructor is called with a pointer to a set of Parameters.
tomwalters@9:  * In the constructor, the module sets the defaults for its various
tomwalters@9:  * parameters.
tomwalters@9:  * A module is initialized with a reference to a valid SignalBank. After the
tomwalters@9:  * Initialize(SignalBank*) function has been called, a call to GetOutputBank()
tomwalters@9:  * returns a pointer to a SignalBank in which the results
tomwalters@9:  * of the module's processing will be placed. Modules can use the output_
tomwalters@9:  * SignalBank to store their output, or leave it uninitialized if they do not
tomwalters@9:  * produce an output.
tomwalters@9:  * At each call to Process(input), the module takes the
tomwalters@9:  * SignalBank 'input' (which must, unless otherwise specified, have the same
tomwalters@9:  * number of channels, sample rate, buffer size and centre frequencies as the
tomwalters@9:  * SignalBank which was passed to Initialize()), processes it, and places the
tomwalters@9:  * output in the internal SignalBank output_.
tomwalters@9:  * Modules can have an arbitrary number of unique targets. Each
tomwalters@9:  * completed output frame is 'pushed' to all of the targets of the module
tomwalters@9:  * in turn when PushOutput() is called. To achieve this, after each complete
tomwalters@9:  * output SignalBank is filled, the module calls the Process() function of
tomwalters@9:  * each of its targets in turn.
tomwalters@9:  * When Initialize() is first called. The module Initialize()s all of its
tomwalters@9:  * targets with its ouptut_ SignalBank, if its output bank has been set up.
tomwalters@9:  *
tomwalters@9:  */
tomwalters@0: class Module {
tomwalters@0:  public:
tomwalters@0:   explicit Module(Parameters *parameters);
tomwalters@0: 
tomwalters@0:   virtual ~Module();
tomwalters@0: 
tomwalters@9:   /* \brief Initialize the module, including calling InitializeInternal().
tomwalters@9:    * Validate this module's output SignalBank, and initialize
tomwalters@0:    * any targets of the module if necessary.
tomwalters@0:    * \param input Input SignalBank.
tomwalters@9:    * \return true on success, false on failure.
tomwalters@3:    *
tomwalters@9:    * A call to Initialize() will first validate the input SignalBank passed to
tomwalters@9:    * it. If this SignalBank is valid, then it will call the
tomwalters@9:    * InitializeInternal() function of the child class; this will set up the 
tomwalters@9:    * child class, and may, if the module produces an output, initialize the
tomwalters@9:    * member variable SignalBank output_. If output_ is initialized after the 
tomwalters@9:    * call to InitializeInternal(), the module will Initialize its targets with
tomwalters@9:    * the output. In this way, it is possible to initialize an entire module 
tomwalters@9:    * tree with a single call to the Initialize() function of the root.
tomwalters@9:    *  
tomwalters@9:    * This function is declared virtual in order to deal with the edge case of
tomwalters@9:    * input modules which do not take a SignalBank as input, but rather
tomwalters@9:    * generate their own input. In this case, it is better to be able to
tomwalters@9:    * override the default Initialize function. When creating a new module, do
tomwalters@9:    * not create a new version of Initialize uness you're sure you know what
tomwalters@9:    * you're doing!
tomwalters@0:    */
tomwalters@3:   virtual bool Initialize(const SignalBank &input);
tomwalters@0: 
tomwalters@9:   /*! \brief Returns true if the module has been correctly initialized
tomwalters@9:    *  \return true if module has been initialized, false otherwise
tomwalters@0:    */
tomwalters@0:   bool initialized() const;
tomwalters@0: 
tomwalters@0:   /* \brief Add a target to this module. Whenever it generates a new
tomwalters@0:    * output, this module will push its output to all its targets.
tomwalters@9:    * \param target_module Pointer to a target Module to add.
tomwalters@9:    * \return true on success, false on failure.
tomwalters@9:    *
tomwalters@9:    * When a pointer is passed as a target to the module, the caller retains
tomwalters@9:    * ownership of the module that it points to. The pointed-to module must
tomwalters@9:    * continue to exist until it is deleted from the target list by a call
tomwalters@9:    * to DeleteTarget() or DeleteAllTargets(), or the current module is
tomwalters@9:    * destroyed. Bad things will happen if the Module pointed to is deleted
tomwalters@9:    * and Initialize(), Reset() or Process() is subsequently called.
tomwalters@0:    */
tomwalters@0:   bool AddTarget(Module* target_module);
tomwalters@0: 
tomwalters@9:   /*! \brief Remove a previously added target module from the list of targets 
tomwalters@9:    *  for this module. 
tomwalters@9:    *  \param target_module Pointer to the module to remove. This must be a
tomwalters@9:    *  pointer that was previously passed to AddTarget() 
tomwalters@9:    *  \return true on success, false on failure. 
tomwalters@0:    */
tomwalters@9:   bool RemoveTarget(Module* target_module);
tomwalters@0: 
tomwalters@9:   /*! \brief Remove all previously added target modules from the list of
tomwalters@9:    *  targets for this module.
tomwalters@0:    */
tomwalters@9:   void RemoveAllTargets();
tomwalters@0: 
tomwalters@9:   /*! \brief Process a buffer.
tomwalters@9:    * \param input SignalBank of the form which was passed to Initialize()
tomwalters@9:    *
tomwalters@9:    * Process is called once for each input SignalBank. When implemented in
tomwalters@9:    * classes inheriting from aimc::Module, P
tomwalters@9:    * this SignalBank contains the (read-only) input to the module. It is
tomwalters@9:    * expected that the input SignalBank will have the same number of channels, 
tomwalters@9:    * buffer length and sample rate as the SignalBank passed to Initialize. 
tomwalters@0:    */
tomwalters@0:   virtual void Process(const SignalBank &input) = 0;
tomwalters@0: 
tomwalters@3:   /*! \brief Reset the internal state of this module and all its children to
tomwalters@3:    *  their initial state.
tomwalters@9:    *
tomwalters@9:    * Like a call to Initialize() will cause all target modules to be
tomwalters@9:    * initialized, a call to Reset() will cause all target modules to be reset. 
tomwalters@0:    */
tomwalters@8:   void Reset();
tomwalters@0: 
tomwalters@9:   /*! \brief Return a pointer to the output SignalBank_ for this class.
tomwalters@9:    *  \return pointer to the SignalBank that this module uses to store its
tomwalters@9:    * output.
tomwalters@0:    */
tomwalters@0:   const SignalBank* GetOutputBank() const;
tomwalters@0: 
tomwalters@23:   string version() const {
tomwalters@23:     return module_version_;
tomwalters@23:   }
tomwalters@23: 
tomwalters@23:   string id() const {
tomwalters@23:     return module_identifier_;
tomwalters@23:   }
tomwalters@23: 
tomwalters@23:   string description() const {
tomwalters@23:     return module_description_;
tomwalters@23:   }
tomwalters@23: 
tomwalters@23:   string type() const {
tomwalters@23:     return module_type_;
tomwalters@23:   }
tomwalters@23: 
tomwalters@0:  protected:
tomwalters@0:   void PushOutput();
tomwalters@0: 
tomwalters@3:   virtual void ResetInternal() = 0;
tomwalters@3: 
tomwalters@0:   virtual bool InitializeInternal(const SignalBank &input) = 0;
tomwalters@0: 
tomwalters@0:   bool initialized_;
tomwalters@0:   set<Module*> targets_;
tomwalters@0:   SignalBank output_;
tomwalters@0:   Parameters* parameters_;
tomwalters@0: 
tomwalters@0:   string module_identifier_;
tomwalters@0:   string module_type_;
tomwalters@0:   string module_description_;
tomwalters@0:   string module_version_;
tomwalters@0: 
tomwalters@0:  private:
tomwalters@0:   DISALLOW_COPY_AND_ASSIGN(Module);
tomwalters@0: };
tomwalters@0: }
tomwalters@0: 
tomwalters@11: #endif  // AIMC_SUPPORT_MODULE_H_