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 #ifdef SG_MATH_EXCEPTION_CLASH
  33 #  include <math.h>
  34 #endif
  35
  36 #ifdef HAVE_WINDOWS_H
  37 #  include <windows.h>
  38 #  include <float.h>
  39 #endif
  40
  41 #include <simgear/misc/props.hxx>
  42
  43
  44 \f
  45 /**
  46  * Basic interface for all FlightGear subsystems.
  47  *
  48  * <p>This is an abstract interface that all FlightGear subsystems
  49  * will eventually implement.  It defines the basic operations for
  50  * each subsystem: initialization, property binding and unbinding, and
  51  * updating.  Interfaces may define additional methods, but the
  52  * preferred way of exchanging information with other subsystems is
  53  * through the property tree.</p>
  54  *
  55  * <p>To publish information through a property, a subsystem should
  56  * bind it to a variable or (if necessary) a getter/setter pair in the
  57  * bind() method, and release the property in the unbind() method:</p>
  58  *
  59  * <pre>
  60  * void MySubsystem::bind ()
  61  * {
  62  *   fgTie("/controls/elevator", &_elevator);
  63  *   fgSetArchivable("/controls/elevator");
  64  * }
  65  *
  66  * void MySubsystem::unbind ()
  67  * {
  68  *   fgUntie("/controls/elevator");
  69  * }
  70  * </pre>
  71  *
  72  * <p>To reference a property (possibly) from another subsystem, there
  73  * are two alternatives.  If the property will be referenced only
  74  * infrequently (say, in the init() method), then the fgGet* methods
  75  * declared in fg_props.hxx are the simplest:</p>
  76  *
  77  * <pre>
  78  * void MySubsystem::init ()
  79  * {
  80  *   _errorMargin = fgGetFloat("/display/error-margin-pct");
  81  * }
  82  * </pre>
  83  *
  84  * <p>On the other hand, if the property will be referenced frequently
  85  * (say, in the update() method), then the hash-table lookup required
  86  * by the fgGet* methods might be too expensive; instead, the
  87  * subsystem should obtain a reference to the actual property node in
  88  * its init() function and use that reference in the main loop:</p>
  89  *
  90  * <pre>
  91  * void MySubsystem::init ()
  92  * {
  93  *   _errorNode = fgGetNode("/display/error-margin-pct", true);
  94  * }
  95  *
  96  * void MySubsystem::update (double delta_time_sec)
  97  * {
  98  *   do_something(_errorNode.getFloatValue());
  99  * }
 100  * </pre>
 101  *
 102  * <p>The node returned will always be a pointer to SGPropertyNode,
 103  * and the subsystem should <em>not</em> delete it in its destructor
 104  * (the pointer belongs to the property tree, not the subsystem).</p>
 105  *
 106  * <p>The program may ask the subsystem to suspend or resume
 107  * sim-time-dependent operations; by default, the suspend() and
 108  * resume() methods set the protected variable <var>_suspended</var>,
 109  * which the subsystem can reference in its update() method, but
 110  * subsystems may also override the suspend() and resume() methods to
 111  * take different actions.</p>
 112  */
 113 class FGSubsystem
 114 {
 115 public:
 116
 117   /**
 118    * Default constructor.
 119    */
 120   FGSubsystem ();
 121
 122   /**
 123    * Virtual destructor to ensure that subclass destructors are called.
 124    */
 125   virtual ~FGSubsystem ();
 126
 127
 128   /**
 129    * Initialize the subsystem.
 130    *
 131    * <p>This method should set up the state of the subsystem, but
 132    * should not bind any properties.  Note that any dependencies on
 133    * the state of other subsystems should be placed here rather than
 134    * in the constructor, so that FlightGear can control the
 135    * initialization order.</p>
 136    */
 137   virtual void init () = 0;
 138
 139
 140   /**
 141    * Acquire the subsystem's property bindings.
 142    *
 143    * <p>This method should bind all properties that the subsystem
 144    * publishes.  It will be invoked after init, but before any
 145    * invocations of update.</p>
 146    */
 147   virtual void bind () = 0;
 148
 149
 150   /**
 151    * Release the subsystem's property bindings.
 152    *
 153    * <p>This method should release all properties that the subsystem
 154    * publishes.  It will be invoked by FlightGear (not the destructor)
 155    * just before the subsystem is removed.</p>
 156    */
 157   virtual void unbind () = 0;
 158
 159
 160   /**
 161    * Update the subsystem.
 162    *
 163    * <p>FlightGear invokes this method every time the subsystem should
 164    * update its state.</p>
 165    *
 166    * @param delta_time_sec The delta time, in seconds, since the last
 167    * update.  On first update, delta time will be 0.
 168    */
 169   virtual void update (double delta_time_sec) = 0;
 170
 171
 172   /**
 173    * Suspend operation of this subsystem.
 174    *
 175    * <p>This method instructs the subsystem to suspend
 176    * sim-time-dependent operations until asked to resume.  The update
 177    * method will still be invoked so that the subsystem can take any
 178    * non-time-dependent actions, such as updating the display.</p>
 179    *
 180    * <p>It is not an error for the suspend method to be invoked when
 181    * the subsystem is already suspended; the invocation should simply
 182    * be ignored.</p>
 183    */
 184   virtual void suspend ();
 185
 186
 187   /**
 188    * Suspend or resum operation of this subsystem.
 189    *
 190    * @param suspended true if the subsystem should be suspended, false
 191    * otherwise.
 192    */
 193   virtual void suspend (bool suspended);
 194
 195
 196   /**
 197    * Resume operation of this subsystem.
 198    *
 199    * <p>This method instructs the subsystem to resume
 200    * sim-time-depended operations.  It is not an error for the resume
 201    * method to be invoked when the subsystem is not suspended; the
 202    * invocation should simply be ignored.</p>
 203    */
 204   virtual void resume ();
 205
 206
 207   /**
 208    * Test whether this subsystem is suspended.
 209    *
 210    * @return true if the subsystem is suspended, false if it is not.
 211    */
 212   virtual bool is_suspended () const;
 213
 214
 215 protected:
 216
 217   mutable SGPropertyNode_ptr _freeze_master_node;
 218   bool _suspended;
 219
 220 };
 221
 222
 223 #endif // __FGFS_HXX
 224
 225 // end of fgfs.hxx