1 // fgfs.hxx -- top level include file for FlightGear.
3 // Written by David Megginson, started 2000-12
5 // Copyright (C) 2000 David Megginson, david@megginson.com
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.
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.
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.
32 #ifdef SG_MATH_EXCEPTION_CLASH
44 * Basic interface for all FlightGear subsystems.
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>
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>
58 * void MySubsystem::bind ()
60 * fgTie("/controls/elevator", &_elevator);
61 * fgSetArchivable("/controls/elevator");
64 * void MySubsystem::unbind ()
66 * fgUntie("/controls/elevator");
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>
76 * void MySubsystem::init ()
78 * _errorMargin = fgGetFloat("/display/error-margin-pct");
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>
89 * void MySubsystem::init ()
91 * _errorNode = fgGetNode("/display/error-margin-pct", true);
94 * void MySubsystem::update ()
96 * do_something(_errorNode.getFloatValue());
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>
109 * Virtual destructor to ensure that subclass destructors are called.
111 virtual ~FGSubsystem ();
115 * Initialize the subsystem.
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>
123 virtual void init () = 0;
127 * Acquire the subsystem's property bindings.
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>
133 virtual void bind () = 0;
137 * Release the subsystem's property bindings.
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>
143 virtual void unbind () = 0;
147 * Update the subsystem.
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>
153 virtual void update (int dt) = 0;