annotate trunk/src/Support/Module.h @ 706:f8e90b5d85fd tip

Delete CARFAC code from this repository. It has been moved to https://github.com/google/carfac Please email me with your github username to get access. I've also created a new mailing list to discuss CARFAC development: https://groups.google.com/forum/#!forum/carfac-dev
author ronw@google.com
date Thu, 18 Jul 2013 20:56:51 +0000
parents 6bc760be184b
children
rev   line source
tomwalters@268 1 // Copyright 2010, Thomas Walters
tomwalters@268 2 //
tomwalters@268 3 // AIM-C: A C++ implementation of the Auditory Image Model
tomwalters@268 4 // http://www.acousticscale.org/AIMC
tomwalters@268 5 //
tomwalters@318 6 // Licensed under the Apache License, Version 2.0 (the "License");
tomwalters@318 7 // you may not use this file except in compliance with the License.
tomwalters@318 8 // You may obtain a copy of the License at
tomwalters@268 9 //
tomwalters@318 10 // http://www.apache.org/licenses/LICENSE-2.0
tomwalters@268 11 //
tomwalters@318 12 // Unless required by applicable law or agreed to in writing, software
tomwalters@318 13 // distributed under the License is distributed on an "AS IS" BASIS,
tomwalters@318 14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
tomwalters@318 15 // See the License for the specific language governing permissions and
tomwalters@318 16 // limitations under the License.
tomwalters@268 17
tomwalters@268 18 /*! \file
tomwalters@268 19 * \brief Base class for all AIM-C modules.
tomwalters@268 20 */
tomwalters@268 21
tomwalters@268 22 /*! \author: Thomas Walters <tom@acousticscale.org>
tomwalters@268 23 * \date 2010/01/23
tomwalters@296 24 * \version \$Id$
tomwalters@268 25 */
tomwalters@268 26
tomwalters@283 27 #ifndef AIMC_SUPPORT_MODULE_H_
tomwalters@283 28 #define AIMC_SUPPORT_MODULE_H_
tomwalters@268 29
tomwalters@323 30 #include <iostream>
tomwalters@268 31 #include <set>
tomwalters@268 32 #include <string>
tomwalters@268 33
tomwalters@268 34 #include "Support/Common.h"
tomwalters@268 35 #include "Support/Parameters.h"
tomwalters@268 36 #include "Support/SignalBank.h"
tomwalters@268 37
tomwalters@268 38 namespace aimc {
tomwalters@323 39 using std::ostream;
tomwalters@268 40 using std::set;
tomwalters@268 41 using std::string;
tomwalters@281 42
tomwalters@281 43 /*! \brief Base class for all AIM-C modules.
tomwalters@281 44 *
tomwalters@281 45 * Module() is a base class, from which all AIM-C modules are derived.
tomwalters@281 46 * Classes deriving from module need to implement, at minimum, the pure
tomwalters@281 47 * virtual public function Module::Process() and the pure virtual private
tomwalters@281 48 * functions Module::InitializeInternal() and Module::ResetInternal().
tomwalters@281 49 * (Note: this is in contravention of
tomwalters@281 50 * <a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Inheritance#Inheritance">
tomwalters@281 51 * this rule on inheritance</a> in the Google style guide, but it is designed
tomwalters@281 52 * to make the implementation of modules as simple as possible.)
tomwalters@281 53 *
tomwalters@281 54 * The module constructor is called with a pointer to a set of Parameters.
tomwalters@281 55 * In the constructor, the module sets the defaults for its various
tomwalters@281 56 * parameters.
tomwalters@281 57 * A module is initialized with a reference to a valid SignalBank. After the
tomwalters@281 58 * Initialize(SignalBank*) function has been called, a call to GetOutputBank()
tomwalters@281 59 * returns a pointer to a SignalBank in which the results
tomwalters@281 60 * of the module's processing will be placed. Modules can use the output_
tomwalters@281 61 * SignalBank to store their output, or leave it uninitialized if they do not
tomwalters@281 62 * produce an output.
tomwalters@281 63 * At each call to Process(input), the module takes the
tomwalters@281 64 * SignalBank 'input' (which must, unless otherwise specified, have the same
tomwalters@281 65 * number of channels, sample rate, buffer size and centre frequencies as the
tomwalters@281 66 * SignalBank which was passed to Initialize()), processes it, and places the
tomwalters@281 67 * output in the internal SignalBank output_.
tomwalters@281 68 * Modules can have an arbitrary number of unique targets. Each
tomwalters@281 69 * completed output frame is 'pushed' to all of the targets of the module
tomwalters@281 70 * in turn when PushOutput() is called. To achieve this, after each complete
tomwalters@281 71 * output SignalBank is filled, the module calls the Process() function of
tomwalters@281 72 * each of its targets in turn.
tomwalters@281 73 * When Initialize() is first called. The module Initialize()s all of its
tomwalters@281 74 * targets with its ouptut_ SignalBank, if its output bank has been set up.
tomwalters@281 75 *
tomwalters@281 76 */
tomwalters@268 77 class Module {
tomwalters@268 78 public:
tomwalters@268 79 explicit Module(Parameters *parameters);
tomwalters@268 80
tomwalters@268 81 virtual ~Module();
tomwalters@268 82
tomwalters@281 83 /* \brief Initialize the module, including calling InitializeInternal().
tomwalters@281 84 * Validate this module's output SignalBank, and initialize
tomwalters@268 85 * any targets of the module if necessary.
tomwalters@268 86 * \param input Input SignalBank.
tomwalters@281 87 * \return true on success, false on failure.
tomwalters@275 88 *
tomwalters@281 89 * A call to Initialize() will first validate the input SignalBank passed to
tomwalters@281 90 * it. If this SignalBank is valid, then it will call the
tomwalters@281 91 * InitializeInternal() function of the child class; this will set up the
tomwalters@281 92 * child class, and may, if the module produces an output, initialize the
tomwalters@281 93 * member variable SignalBank output_. If output_ is initialized after the
tomwalters@281 94 * call to InitializeInternal(), the module will Initialize its targets with
tomwalters@281 95 * the output. In this way, it is possible to initialize an entire module
tomwalters@281 96 * tree with a single call to the Initialize() function of the root.
tomwalters@281 97 *
tomwalters@281 98 * This function is declared virtual in order to deal with the edge case of
tomwalters@281 99 * input modules which do not take a SignalBank as input, but rather
tomwalters@281 100 * generate their own input. In this case, it is better to be able to
tomwalters@281 101 * override the default Initialize function. When creating a new module, do
tomwalters@281 102 * not create a new version of Initialize uness you're sure you know what
tomwalters@281 103 * you're doing!
tomwalters@401 104 *
tomwalters@401 105 * global_parameters stores things like the input filename, output filenames
tomwalters@401 106 * and any other metadata that modules might want to share. If present, it
tomwalters@401 107 * is propagated to all children. These parameters are mutable and may
tomwalters@401 108 * change.
tomwalters@268 109 */
tomwalters@401 110 virtual bool Initialize(const SignalBank &input,
tomwalters@401 111 Parameters *global_parameters);
tomwalters@268 112
tomwalters@281 113 /*! \brief Returns true if the module has been correctly initialized
tomwalters@281 114 * \return true if module has been initialized, false otherwise
tomwalters@268 115 */
tomwalters@268 116 bool initialized() const;
tomwalters@268 117
tomwalters@268 118 /* \brief Add a target to this module. Whenever it generates a new
tomwalters@268 119 * output, this module will push its output to all its targets.
tomwalters@281 120 * \param target_module Pointer to a target Module to add.
tomwalters@281 121 * \return true on success, false on failure.
tomwalters@281 122 *
tomwalters@281 123 * When a pointer is passed as a target to the module, the caller retains
tomwalters@281 124 * ownership of the module that it points to. The pointed-to module must
tomwalters@281 125 * continue to exist until it is deleted from the target list by a call
tomwalters@281 126 * to DeleteTarget() or DeleteAllTargets(), or the current module is
tomwalters@281 127 * destroyed. Bad things will happen if the Module pointed to is deleted
tomwalters@281 128 * and Initialize(), Reset() or Process() is subsequently called.
tomwalters@268 129 */
tomwalters@268 130 bool AddTarget(Module* target_module);
tomwalters@268 131
tomwalters@281 132 /*! \brief Remove a previously added target module from the list of targets
tomwalters@281 133 * for this module.
tomwalters@281 134 * \param target_module Pointer to the module to remove. This must be a
tomwalters@281 135 * pointer that was previously passed to AddTarget()
tomwalters@281 136 * \return true on success, false on failure.
tomwalters@268 137 */
tomwalters@281 138 bool RemoveTarget(Module* target_module);
tomwalters@268 139
tomwalters@281 140 /*! \brief Remove all previously added target modules from the list of
tomwalters@281 141 * targets for this module.
tomwalters@268 142 */
tomwalters@281 143 void RemoveAllTargets();
tomwalters@268 144
tomwalters@281 145 /*! \brief Process a buffer.
tomwalters@281 146 * \param input SignalBank of the form which was passed to Initialize()
tomwalters@281 147 *
tomwalters@281 148 * Process is called once for each input SignalBank. When implemented in
tomwalters@281 149 * classes inheriting from aimc::Module, P
tomwalters@281 150 * this SignalBank contains the (read-only) input to the module. It is
tomwalters@281 151 * expected that the input SignalBank will have the same number of channels,
tomwalters@281 152 * buffer length and sample rate as the SignalBank passed to Initialize.
tomwalters@268 153 */
tomwalters@268 154 virtual void Process(const SignalBank &input) = 0;
tomwalters@268 155
tomwalters@275 156 /*! \brief Reset the internal state of this module and all its children to
tomwalters@275 157 * their initial state.
tomwalters@281 158 *
tomwalters@281 159 * Like a call to Initialize() will cause all target modules to be
tomwalters@281 160 * initialized, a call to Reset() will cause all target modules to be reset.
tomwalters@268 161 */
tomwalters@280 162 void Reset();
tomwalters@268 163
tomwalters@281 164 /*! \brief Return a pointer to the output SignalBank_ for this class.
tomwalters@281 165 * \return pointer to the SignalBank that this module uses to store its
tomwalters@281 166 * output.
tomwalters@268 167 */
tomwalters@268 168 const SignalBank* GetOutputBank() const;
tomwalters@268 169
tomwalters@323 170 void PrintTargets(ostream &out);
tomwalters@402 171 void PrintTargetsForDot(ostream &out);
tomwalters@402 172 void PrintConfiguration(ostream &out);
tomwalters@323 173
tomwalters@296 174 string version() const {
tomwalters@296 175 return module_version_;
tomwalters@296 176 }
tomwalters@296 177
tomwalters@296 178 string id() const {
tomwalters@296 179 return module_identifier_;
tomwalters@296 180 }
tomwalters@296 181
tomwalters@296 182 string description() const {
tomwalters@296 183 return module_description_;
tomwalters@296 184 }
tomwalters@296 185
tomwalters@296 186 string type() const {
tomwalters@296 187 return module_type_;
tomwalters@296 188 }
tomwalters@402 189
tomwalters@402 190 bool done() {
tomwalters@402 191 return done_;
tomwalters@402 192 }
tomwalters@402 193
tomwalters@402 194 void set_instance_name(string instance_name) {
tomwalters@402 195 instance_name_ = instance_name;
tomwalters@402 196 }
tomwalters@402 197
tomwalters@402 198 string instance_name() {
tomwalters@402 199 return instance_name_;
tomwalters@402 200 }
tomwalters@296 201
tomwalters@268 202 protected:
tomwalters@268 203 void PushOutput();
tomwalters@268 204
tomwalters@275 205 virtual void ResetInternal() = 0;
tomwalters@275 206
tomwalters@268 207 virtual bool InitializeInternal(const SignalBank &input) = 0;
tomwalters@268 208
tomwalters@268 209 bool initialized_;
tomwalters@402 210 bool done_;
tomwalters@268 211 set<Module*> targets_;
tomwalters@268 212 SignalBank output_;
tomwalters@268 213 Parameters* parameters_;
tomwalters@401 214 Parameters* global_parameters_;
tomwalters@268 215
tomwalters@268 216 string module_identifier_;
tomwalters@268 217 string module_type_;
tomwalters@268 218 string module_description_;
tomwalters@268 219 string module_version_;
tomwalters@402 220
tomwalters@402 221 string instance_name_;
tomwalters@268 222
tomwalters@268 223 private:
tomwalters@268 224 DISALLOW_COPY_AND_ASSIGN(Module);
tomwalters@268 225 };
tomwalters@268 226 }
tomwalters@268 227
tomwalters@283 228 #endif // AIMC_SUPPORT_MODULE_H_