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
  42 \f
  43 /**
  44  * Basic interface for all FlightGear subsystems.
  45  *
  46  * <p>This is an abstract interface that all FlightGear subsystems
  47  * will eventually implement.  It defines the basic operations for
  48  * each subsystem: initialization, property binding and unbinding, and
  49  * updating.  Interfaces may define additional methods, but the
  50  * preferred way of exchanging information with other subsystems is
  51  * through the property tree.</p>
  52  *
  53  * <p>To publish information through a property, a subsystem should
  54  * bind it to a variable or (if necessary) a getter/setter pair in the
  55  * bind() method, and release the property in the unbind() method:</p>
  56  *
  57  * <pre>
  58  * void MySubsystem::bind ()
  59  * {
  60  *   fgTie("/controls/elevator", &_elevator);
  61  *   fgSetArchivable("/controls/elevator");
  62  * }
  63  *
  64  * void MySubsystem::unbind ()
  65  * {
  66  *   fgUntie("/controls/elevator");
  67  * }
  68  * </pre>
  69  *
  70  * <p>To reference a property (possibly) from another subsystem, there
  71  * are two alternatives.  If the property will be referenced only
  72  * infrequently (say, in the init() method), then the fgGet* methods
  73  * declared in fg_props.hxx are the simplest:</p>
  74  *
  75  * <pre>
  76  * void MySubsystem::init ()
  77  * {
  78  *   _errorMargin = fgGetFloat("/display/error-margin-pct");
  79  * }
  80  * </pre>
  81  *
  82  * <p>On the other hand, if the property will be referenced frequently
  83  * (say, in the update() method), then the hash-table lookup required
  84  * by the fgGet* methods might be too expensive; instead, the
  85  * subsystem should obtain a reference to the actual property node in
  86  * its init() function and use that reference in the main loop:</p>
  87  *
  88  * <pre>
  89  * void MySubsystem::init ()
  90  * {
  91  *   _errorNode = fgGetNode("/display/error-margin-pct", true);
  92  * }
  93  *
  94  * void MySubsystem::update ()
  95  * {
  96  *   do_something(_errorNode.getFloatValue());
  97  * }
  98  * </pre>
  99  *
 100  * <p>The node returned will always be a pointer to SGPropertyNode,
 101  * and the subsystem should <em>not</em> delete it in its destructor
 102  * (the pointer belongs to the property tree, not the subsystem).</p>
 103  */
 104 class FGSubsystem
 105 {
 106 public:
 107
 108   /**
 109    * Virtual destructor to ensure that subclass destructors are called.
 110    */
 111   virtual ~FGSubsystem ();
 112
 113
 114   /**
 115    * Initialize the subsystem.
 116    *
 117    * <p>This method should set up the state of the subsystem, but
 118    * should not bind any properties.  Note that any dependencies on
 119    * the state of other subsystems should be placed here rather than
 120    * in the constructor, so that FlightGear can control the
 121    * initialization order.</p>
 122    */
 123   virtual void init () = 0;
 124
 125
 126   /**
 127    * Acquire the subsystem's property bindings.
 128    *
 129    * <p>This method should bind all properties that the subsystem
 130    * publishes.  It will be invoked after init, but before any
 131    * invocations of update.</p>
 132    */
 133   virtual void bind () = 0;
 134
 135
 136   /**
 137    * Release the subsystem's property bindings.
 138    *
 139    * <p>This method should release all properties that the subsystem
 140    * publishes.  It will be invoked by FlightGear (not the destructor)
 141    * just before the subsystem is removed.</p>
 142    */
 143   virtual void unbind () = 0;
 144
 145
 146   /**
 147    * Update the subsystem.
 148    *
 149    * <p>FlightGear invokes this method every time the subsystem should
 150    * update its state.  If the subsystem requires delta time information,
 151    * it should track it itself.</p>
 152    */
 153   virtual void update (int dt) = 0;
 154
 155 };
 156
 157
 158 #endif // __FGFS_HXX
 159
 160 // end of fgfs.hxx