src/Main/fgfs.hxx

   1 // fgfs.hxx -- top level include file for FlightGear.
   2 //
   3 // Written by David Megginson, started 2000-12
   4 //
   5 // Copyright (C) 2000  David Megginson, david@megginson.com
   6 //
   7 // This program is free software; you can redistribute it and/or
   8 // modify it under the terms of the GNU General Public License as
   9 // published by the Free Software Foundation; either version 2 of the
  10 // License, or (at your option) any later version.
  11 //
  12 // This program is distributed in the hope that it will be useful, but
  13 // WITHOUT ANY WARRANTY; without even the implied warranty of
  14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 // General Public License for more details.
  16 //
  17 // You should have received a copy of the GNU General Public License
  18 // along with this program; if not, write to the Free Software
  19 // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20 //
  21 // $Id$
  22
  23
  24 #ifndef __FGFS_HXX
  25 #define __FGFS_HXX 1
  26
  27
  28 #ifdef HAVE_CONFIG_H
  29 #  include <config.h>
  30 #endif
  31
  32 #include <simgear/compiler.h>
  33
  34 // #ifdef SG_MATH_EXCEPTION_CLASH
  35 // #  include <math.h>
  36 // #endif
  37
  38 #ifdef HAVE_WINDOWS_H
  39 #  include <windows.h>
  40 #  include <float.h>
  41 #endif
  42
  43 #include STL_STRING
  44 SG_USING_STD(string);
  45
  46 #include <vector>
  47 SG_USING_STD(vector);
  48
  49 #include <map>
  50 SG_USING_STD(map);
  51
  52 #include <simgear/misc/props.hxx>
  53
  54
  55 \f
  56 /**
  57  * Basic interface for all FlightGear subsystems.
  58  *
  59  * <p>This is an abstract interface that all FlightGear subsystems
  60  * will eventually implement.  It defines the basic operations for
  61  * each subsystem: initialization, property binding and unbinding, and
  62  * updating.  Interfaces may define additional methods, but the
  63  * preferred way of exchanging information with other subsystems is
  64  * through the property tree.</p>
  65  *
  66  * <p>To publish information through a property, a subsystem should
  67  * bind it to a variable or (if necessary) a getter/setter pair in the
  68  * bind() method, and release the property in the unbind() method:</p>
  69  *
  70  * <pre>
  71  * void MySubsystem::bind ()
  72  * {
  73  *   fgTie("/controls/flight/elevator", &_elevator);
  74  *   fgSetArchivable("/controls/flight/elevator");
  75  * }
  76  *
  77  * void MySubsystem::unbind ()
  78  * {
  79  *   fgUntie("/controls/flight/elevator");
  80  * }
  81  * </pre>
  82  *
  83  * <p>To reference a property (possibly) from another subsystem, there
  84  * are two alternatives.  If the property will be referenced only
  85  * infrequently (say, in the init() method), then the fgGet* methods
  86  * declared in fg_props.hxx are the simplest:</p>
  87  *
  88  * <pre>
  89  * void MySubsystem::init ()
  90  * {
  91  *   _errorMargin = fgGetFloat("/display/error-margin-pct");
  92  * }
  93  * </pre>
  94  *
  95  * <p>On the other hand, if the property will be referenced frequently
  96  * (say, in the update() method), then the hash-table lookup required
  97  * by the fgGet* methods might be too expensive; instead, the
  98  * subsystem should obtain a reference to the actual property node in
  99  * its init() function and use that reference in the main loop:</p>
 100  *
 101  * <pre>
 102  * void MySubsystem::init ()
 103  * {
 104  *   _errorNode = fgGetNode("/display/error-margin-pct", true);
 105  * }
 106  *
 107  * void MySubsystem::update (double delta_time_sec)
 108  * {
 109  *   do_something(_errorNode.getFloatValue());
 110  * }
 111  * </pre>
 112  *
 113  * <p>The node returned will always be a pointer to SGPropertyNode,
 114  * and the subsystem should <em>not</em> delete it in its destructor
 115  * (the pointer belongs to the property tree, not the subsystem).</p>
 116  *
 117  * <p>The program may ask the subsystem to suspend or resume
 118  * sim-time-dependent operations; by default, the suspend() and
 119  * resume() methods set the protected variable <var>_suspended</var>,
 120  * which the subsystem can reference in its update() method, but
 121  * subsystems may also override the suspend() and resume() methods to
 122  * take different actions.</p>
 123  */
 124 class FGSubsystem
 125 {
 126 public:
 127
 128   /**
 129    * Default constructor.
 130    */
 131   FGSubsystem ();
 132
 133   /**
 134    * Virtual destructor to ensure that subclass destructors are called.
 135    */
 136   virtual ~FGSubsystem ();
 137
 138
 139   /**
 140    * Initialize the subsystem.
 141    *
 142    * <p>This method should set up the state of the subsystem, but
 143    * should not bind any properties.  Note that any dependencies on
 144    * the state of other subsystems should be placed here rather than
 145    * in the constructor, so that FlightGear can control the
 146    * initialization order.</p>
 147    */
 148   virtual void init ();
 149
 150
 151   /**
 152    * Reinitialize the subsystem.
 153    *
 154    * <p>This method should cause the subsystem to reinitialize itself,
 155    * and (normally) to reload any configuration files.</p>
 156    */
 157   virtual void reinit ();
 158
 159
 160   /**
 161    * Acquire the subsystem's property bindings.
 162    *
 163    * <p>This method should bind all properties that the subsystem
 164    * publishes.  It will be invoked after init, but before any
 165    * invocations of update.</p>
 166    */
 167   virtual void bind ();
 168
 169
 170   /**
 171    * Release the subsystem's property bindings.
 172    *
 173    * <p>This method should release all properties that the subsystem
 174    * publishes.  It will be invoked by FlightGear (not the destructor)
 175    * just before the subsystem is removed.</p>
 176    */
 177   virtual void unbind ();
 178
 179
 180   /**
 181    * Update the subsystem.
 182    *
 183    * <p>FlightGear invokes this method every time the subsystem should
 184    * update its state.</p>
 185    *
 186    * @param delta_time_sec The delta time, in seconds, since the last
 187    * update.  On first update, delta time will be 0.
 188    */
 189   virtual void update (double delta_time_sec) = 0;
 190
 191
 192   /**
 193    * Suspend operation of this subsystem.
 194    *
 195    * <p>This method instructs the subsystem to suspend
 196    * sim-time-dependent operations until asked to resume.  The update
 197    * method will still be invoked so that the subsystem can take any
 198    * non-time-dependent actions, such as updating the display.</p>
 199    *
 200    * <p>It is not an error for the suspend method to be invoked when
 201    * the subsystem is already suspended; the invocation should simply
 202    * be ignored.</p>
 203    */
 204   virtual void suspend ();
 205
 206
 207   /**
 208    * Suspend or resum operation of this subsystem.
 209    *
 210    * @param suspended true if the subsystem should be suspended, false
 211    * otherwise.
 212    */
 213   virtual void suspend (bool suspended);
 214
 215
 216   /**
 217    * Resume operation of this subsystem.
 218    *
 219    * <p>This method instructs the subsystem to resume
 220    * sim-time-depended operations.  It is not an error for the resume
 221    * method to be invoked when the subsystem is not suspended; the
 222    * invocation should simply be ignored.</p>
 223    */
 224   virtual void resume ();
 225
 226
 227   /**
 228    * Test whether this subsystem is suspended.
 229    *
 230    * @return true if the subsystem is suspended, false if it is not.
 231    */
 232   virtual bool is_suspended () const;
 233
 234
 235 protected:
 236
 237   mutable SGPropertyNode_ptr _freeze_master_node;
 238   bool _suspended;
 239
 240 };
 241
 242
 243 \f
 244 /**
 245  * A group of FlightGear subsystems.
 246  */
 247 class FGSubsystemGroup : public FGSubsystem
 248 {
 249 public:
 250
 251     FGSubsystemGroup ();
 252     virtual ~FGSubsystemGroup ();
 253
 254     virtual void init ();
 255     virtual void reinit ();
 256     virtual void bind ();
 257     virtual void unbind ();
 258     virtual void update (double delta_time_sec);
 259     virtual void suspend ();
 260     virtual void resume ();
 261     virtual bool is_suspended () const;
 262
 263     virtual void set_subsystem (const string &name,
 264                                 FGSubsystem * subsystem,
 265                                 double min_step_sec = 0);
 266     virtual FGSubsystem * get_subsystem (const string &name);
 267     virtual void remove_subsystem (const string &name);
 268     virtual bool has_subsystem (const string &name) const;
 269
 270 private:
 271
 272     struct Member {
 273
 274         Member ();
 275         Member (const Member &member);
 276         virtual ~Member ();
 277
 278         virtual void update (double delta_time_sec);
 279
 280         string name;
 281         FGSubsystem * subsystem;
 282         double min_step_sec;
 283         double elapsed_sec;
 284     };
 285
 286     Member * get_member (const string &name, bool create = false);
 287
 288     vector<Member *> _members;
 289 };
 290
 291
 292 \f
 293 /**
 294  * Manage subsystems for FlightGear.
 295  *
 296  * This top-level subsystem will eventually manage all of the
 297  * subsystems in FlightGear: it broadcasts its life-cycle events
 298  * (init, bind, etc.) to all of the subsystems it manages.  Subsystems
 299  * are grouped to guarantee order of initialization and execution --
 300  * currently, the only two groups are INIT and GENERAL, but others
 301  * will appear in the future.
 302  *
 303  * All subsystems are named as well as grouped, and subsystems can be
 304  * looked up by name and cast to the appropriate subtype when another
 305  * subsystem needs to invoke specialized methods.
 306  *
 307  * The subsystem manager owns the pointers to all the subsystems in
 308  * it.
 309  */
 310 class FGSubsystemMgr : public FGSubsystem
 311 {
 312 public:
 313
 314     /**
 315      * Types of subsystem groups.
 316      */
 317     enum GroupType {
 318         INIT = 0,
 319         GENERAL,
 320         MAX_GROUPS
 321     };
 322
 323     FGSubsystemMgr ();
 324     virtual ~FGSubsystemMgr ();
 325
 326     virtual void init ();
 327     virtual void reinit ();
 328     virtual void bind ();
 329     virtual void unbind ();
 330     virtual void update (double delta_time_sec);
 331     virtual void suspend ();
 332     virtual void resume ();
 333     virtual bool is_suspended () const;
 334
 335     virtual void add (const char * name,
 336                       FGSubsystem * subsystem,
 337                       GroupType group = GENERAL,
 338                       double min_time_sec = 0);
 339
 340     virtual FGSubsystemGroup * get_group (GroupType group);
 341
 342     virtual FGSubsystem * get_subsystem(const string &name);
 343
 344 private:
 345
 346     FGSubsystemGroup _groups[MAX_GROUPS];
 347     map<string,FGSubsystem *> _subsystem_map;
 348
 349 };
 350
 351
 352
 353 #endif // __FGFS_HXX
 354
 355 // end of fgfs.hxx