1 // Written by David Megginson, started 2000-12
3 // Copyright (C) 2000 David Megginson, david@megginson.com
5 // This program is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU General Public License as
7 // published by the Free Software Foundation; either version 2 of the
8 // License, or (at your option) any later version.
10 // This program is distributed in the hope that it will be useful, but
11 // WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // General Public License for more details.
15 // You should have received a copy of the GNU General Public License
16 // along with this program; if not, write to the Free Software
17 // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
22 #ifndef __SUBSYSTEM_MGR_HXX
23 #define __SUBSYSTEM_MGR_HXX 1
26 #include <simgear/compiler.h>
44 #include <simgear/props/props.hxx>
49 * Basic interface for all FlightGear subsystems.
51 * <p>This is an abstract interface that all FlightGear subsystems
52 * will eventually implement. It defines the basic operations for
53 * each subsystem: initialization, property binding and unbinding, and
54 * updating. Interfaces may define additional methods, but the
55 * preferred way of exchanging information with other subsystems is
56 * through the property tree.</p>
58 * <p>To publish information through a property, a subsystem should
59 * bind it to a variable or (if necessary) a getter/setter pair in the
60 * bind() method, and release the property in the unbind() method:</p>
63 * void MySubsystem::bind ()
65 * fgTie("/controls/flight/elevator", &_elevator);
66 * fgSetArchivable("/controls/flight/elevator");
69 * void MySubsystem::unbind ()
71 * fgUntie("/controls/flight/elevator");
75 * <p>To reference a property (possibly) from another subsystem, there
76 * are two alternatives. If the property will be referenced only
77 * infrequently (say, in the init() method), then the fgGet* methods
78 * declared in fg_props.hxx are the simplest:</p>
81 * void MySubsystem::init ()
83 * _errorMargin = fgGetFloat("/display/error-margin-pct");
87 * <p>On the other hand, if the property will be referenced frequently
88 * (say, in the update() method), then the hash-table lookup required
89 * by the fgGet* methods might be too expensive; instead, the
90 * subsystem should obtain a reference to the actual property node in
91 * its init() function and use that reference in the main loop:</p>
94 * void MySubsystem::init ()
96 * _errorNode = fgGetNode("/display/error-margin-pct", true);
99 * void MySubsystem::update (double delta_time_sec)
101 * do_something(_errorNode.getFloatValue());
105 * <p>The node returned will always be a pointer to SGPropertyNode,
106 * and the subsystem should <em>not</em> delete it in its destructor
107 * (the pointer belongs to the property tree, not the subsystem).</p>
109 * <p>The program may ask the subsystem to suspend or resume
110 * sim-time-dependent operations; by default, the suspend() and
111 * resume() methods set the protected variable <var>_suspended</var>,
112 * which the subsystem can reference in its update() method, but
113 * subsystems may also override the suspend() and resume() methods to
114 * take different actions.</p>
121 * Default constructor.
126 * Virtual destructor to ensure that subclass destructors are called.
128 virtual ~SGSubsystem ();
132 * Initialize the subsystem.
134 * <p>This method should set up the state of the subsystem, but
135 * should not bind any properties. Note that any dependencies on
136 * the state of other subsystems should be placed here rather than
137 * in the constructor, so that FlightGear can control the
138 * initialization order.</p>
140 virtual void init ();
144 * Reinitialize the subsystem.
146 * <p>This method should cause the subsystem to reinitialize itself,
147 * and (normally) to reload any configuration files.</p>
149 virtual void reinit ();
153 * Acquire the subsystem's property bindings.
155 * <p>This method should bind all properties that the subsystem
156 * publishes. It will be invoked after init, but before any
157 * invocations of update.</p>
159 virtual void bind ();
163 * Release the subsystem's property bindings.
165 * <p>This method should release all properties that the subsystem
166 * publishes. It will be invoked by FlightGear (not the destructor)
167 * just before the subsystem is removed.</p>
169 virtual void unbind ();
173 * Update the subsystem.
175 * <p>FlightGear invokes this method every time the subsystem should
176 * update its state.</p>
178 * @param delta_time_sec The delta time, in seconds, since the last
179 * update. On first update, delta time will be 0.
181 virtual void update (double delta_time_sec) = 0;
185 * Suspend operation of this subsystem.
187 * <p>This method instructs the subsystem to suspend
188 * sim-time-dependent operations until asked to resume. The update
189 * method will still be invoked so that the subsystem can take any
190 * non-time-dependent actions, such as updating the display.</p>
192 * <p>It is not an error for the suspend method to be invoked when
193 * the subsystem is already suspended; the invocation should simply
196 virtual void suspend ();
200 * Suspend or resum operation of this subsystem.
202 * @param suspended true if the subsystem should be suspended, false
205 virtual void suspend (bool suspended);
209 * Resume operation of this subsystem.
211 * <p>This method instructs the subsystem to resume
212 * sim-time-depended operations. It is not an error for the resume
213 * method to be invoked when the subsystem is not suspended; the
214 * invocation should simply be ignored.</p>
216 virtual void resume ();
220 * Test whether this subsystem is suspended.
222 * @return true if the subsystem is suspended, false if it is not.
224 virtual bool is_suspended () const;
236 * A group of FlightGear subsystems.
238 class SGSubsystemGroup : public SGSubsystem
243 virtual ~SGSubsystemGroup ();
245 virtual void init ();
246 virtual void reinit ();
247 virtual void bind ();
248 virtual void unbind ();
249 virtual void update (double delta_time_sec);
250 virtual void suspend ();
251 virtual void resume ();
252 virtual bool is_suspended () const;
254 virtual void set_subsystem (const string &name,
255 SGSubsystem * subsystem,
256 double min_step_sec = 0);
257 virtual SGSubsystem * get_subsystem (const string &name);
258 virtual void remove_subsystem (const string &name);
259 virtual bool has_subsystem (const string &name) const;
266 Member (const Member &member);
269 virtual void update (double delta_time_sec);
272 SGSubsystem * subsystem;
277 Member * get_member (const string &name, bool create = false);
279 vector<Member *> _members;
285 * Manage subsystems for FlightGear.
287 * This top-level subsystem will eventually manage all of the
288 * subsystems in FlightGear: it broadcasts its life-cycle events
289 * (init, bind, etc.) to all of the subsystems it manages. Subsystems
290 * are grouped to guarantee order of initialization and execution --
291 * currently, the only two groups are INIT and GENERAL, but others
292 * will appear in the future.
294 * All subsystems are named as well as grouped, and subsystems can be
295 * looked up by name and cast to the appropriate subtype when another
296 * subsystem needs to invoke specialized methods.
298 * The subsystem manager owns the pointers to all the subsystems in
301 class SGSubsystemMgr : public SGSubsystem
306 * Types of subsystem groups.
315 virtual ~SGSubsystemMgr ();
317 virtual void init ();
318 virtual void reinit ();
319 virtual void bind ();
320 virtual void unbind ();
321 virtual void update (double delta_time_sec);
322 virtual void suspend ();
323 virtual void resume ();
324 virtual bool is_suspended () const;
326 virtual void add (const char * name,
327 SGSubsystem * subsystem,
328 GroupType group = GENERAL,
329 double min_time_sec = 0);
331 virtual SGSubsystemGroup * get_group (GroupType group);
333 virtual SGSubsystem * get_subsystem(const string &name);
337 SGSubsystemGroup _groups[MAX_GROUPS];
338 map<string,SGSubsystem *> _subsystem_map;
344 #endif // __SUBSYSTEM_MGR_HXX