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@45: // Licensed under the Apache License, Version 2.0 (the "License"); tomwalters@45: // you may not use this file except in compliance with the License. tomwalters@45: // You may obtain a copy of the License at tomwalters@0: // tomwalters@45: // http://www.apache.org/licenses/LICENSE-2.0 tomwalters@0: // tomwalters@45: // Unless required by applicable law or agreed to in writing, software tomwalters@45: // distributed under the License is distributed on an "AS IS" BASIS, tomwalters@45: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. tomwalters@45: // See the License for the specific language governing permissions and tomwalters@45: // limitations under the License. tomwalters@0: tomwalters@0: /*! \file tomwalters@0: * \brief Base class for all AIM-C modules. tomwalters@0: */ tomwalters@0: tomwalters@0: /*! \author: Thomas Walters 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@52: // Several modules expect the M_PI macro and isnan() to be defined tomwalters@52: #ifdef _MSC_VER tomwalters@52: #define M_PI 3.14159265359 tomwalters@52: #define isnan _isnan tomwalters@52: #define isinf _isinf tomwalters@52: #endif tomwalters@52: tomwalters@49: #include tomwalters@0: #include tomwalters@0: #include 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@49: using std::ostream; 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: * tomwalters@9: * this rule on inheritance 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@49: void PrintTargets(ostream &out); tomwalters@49: tomwalters@49: void PrintVersions(ostream &out); tomwalters@49: 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 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_