SGSubsystem Class Reference

Basic interface for all FlightGear subsystems. More...

#include <subsystem_mgr.hxx>

Inheritance diagram for SGSubsystem:

Public Member Functions
	SGSubsystem ()
	Default constructor.
virtual	~SGSubsystem ()
	Virtual destructor to ensure that subclass destructors are called.
virtual void	init ()
	Initialize the subsystem.
virtual void	postinit ()
	Initialize parts that depend on other subsystems having been initialized.
virtual void	reinit ()
	Reinitialize the subsystem.
virtual void	bind ()
	Acquire the subsystem's property bindings.
virtual void	unbind ()
	Release the subsystem's property bindings.
virtual void	update (double delta_time_sec)=0
	Update the subsystem.
virtual void	suspend ()
	Suspend operation of this subsystem.
virtual void	suspend (bool suspended)
	Suspend or resum operation of this subsystem.
virtual void	resume ()
	Resume operation of this subsystem.
virtual bool	is_suspended () const
	Test whether this subsystem is suspended.
void	updateExecutionTime (double time)
	Keep track of execution time.
void	printTimingInformation ()
	Print details of execution time.
void	stamp (const string &name)
	Place time stamps at strategic points in the execution of subsystems update() member functions.

Detailed Description

Basic interface for all FlightGear subsystems.

This is an abstract interface that all FlightGear subsystems will eventually implement. It defines the basic operations for each subsystem: initialization, property binding and unbinding, and updating. Interfaces may define additional methods, but the preferred way of exchanging information with other subsystems is through the property tree.

To publish information through a property, a subsystem should bind it to a variable or (if necessary) a getter/setter pair in the bind() method, and release the property in the unbind() method:

 void MySubsystem::bind ()
 {
   fgTie("/controls/flight/elevator", &_elevator);
   fgSetArchivable("/controls/flight/elevator");
 }

 void MySubsystem::unbind ()
 {
   fgUntie("/controls/flight/elevator");
 }

To reference a property (possibly) from another subsystem, there are two alternatives. If the property will be referenced only infrequently (say, in the init() method), then the fgGet* methods declared in fg_props.hxx are the simplest:

 void MySubsystem::init ()
 {
   _errorMargin = fgGetFloat("/display/error-margin-pct");
 }

On the other hand, if the property will be referenced frequently (say, in the update() method), then the hash-table lookup required by the fgGet* methods might be too expensive; instead, the subsystem should obtain a reference to the actual property node in its init() function and use that reference in the main loop:

 void MySubsystem::init ()
 {
   _errorNode = fgGetNode("/display/error-margin-pct", true);
 }

 void MySubsystem::update (double delta_time_sec)
 {
   do_something(_errorNode.getFloatValue());
 }

The node returned will always be a pointer to SGPropertyNode, and the subsystem should not delete it in its destructor (the pointer belongs to the property tree, not the subsystem).

The program may ask the subsystem to suspend or resume sim-time-dependent operations; by default, the suspend() and resume() methods set the protected variable _suspended, which the subsystem can reference in its update() method, but subsystems may also override the suspend() and resume() methods to take different actions.

Definition at line 128 of file subsystem_mgr.hxx.

Member Function Documentation

void SGSubsystem::bind ( ) [virtual]

Acquire the subsystem's property bindings.

This method should bind all properties that the subsystem publishes. It will be invoked after init, but before any invocations of update.

Reimplemented in SGSubsystemGroup, SGSubsystemMgr, SGSoundMgr, and SGSoundMgr.

Definition at line 42 of file subsystem_mgr.cxx.

void SGSubsystem::init ( void ) [virtual]

Initialize the subsystem.

This method should set up the state of the subsystem, but should not bind any properties. Note that any dependencies on the state of other subsystems should be placed here rather than in the constructor, so that FlightGear can control the initialization order.

Reimplemented in SGSubsystemGroup, SGSubsystemMgr, and SGSoundMgr.

Definition at line 27 of file subsystem_mgr.cxx.

bool SGSubsystem::is_suspended ( ) const [virtual]

Test whether this subsystem is suspended.

Returns:: true if the subsystem is suspended, false if it is not.

Reimplemented in SGSubsystemGroup, and SGSubsystemMgr.

Definition at line 70 of file subsystem_mgr.cxx.

void SGSubsystem::postinit ( ) [virtual]

Initialize parts that depend on other subsystems having been initialized.

This method should set up all parts that depend on other subsystems. One example is the scripting/Nasal subsystem, which is initialized last. So, if a subsystem wants to execute Nasal code in subsystem-specific configuration files, it has to do that in its postinit() method.

Reimplemented in SGSubsystemGroup, and SGSubsystemMgr.

Definition at line 32 of file subsystem_mgr.cxx.

void SGSubsystem::printTimingInformation ( )

Print details of execution time.

For debugging purposes, developers can place stamp() calls at strategic points in the update() function of each subsystem, which record the time between the successive calls to stamp. This method, printExecutionTime() is called after exectution of the subsystem update function itself to conduct a post-hoc analysis of excecution time

Definition at line 77 of file subsystem_mgr.cxx.

void SGSubsystem::reinit ( ) [virtual]

Reinitialize the subsystem.

This method should cause the subsystem to reinitialize itself, and (normally) to reload any configuration files.

Reimplemented in SGSubsystemGroup, SGSubsystemMgr, SGSoundMgr, and SGSoundMgr.

Definition at line 37 of file subsystem_mgr.cxx.

void SGSubsystem::resume ( ) [virtual]

Resume operation of this subsystem.

This method instructs the subsystem to resume sim-time-depended operations. It is not an error for the resume method to be invoked when the subsystem is not suspended; the invocation should simply be ignored.

Reimplemented in SGSubsystemGroup, SGSubsystemMgr, SGSoundMgr, and SGSoundMgr.

Definition at line 64 of file subsystem_mgr.cxx.

void SGSubsystem::stamp ( const string & name )

Place time stamps at strategic points in the execution of subsystems update() member functions.

Predominantly for debugging purposes.

Definition at line 97 of file subsystem_mgr.cxx.

void SGSubsystem::suspend ( bool suspended ) [virtual]

Suspend or resum operation of this subsystem.

Parameters:

suspended

true if the subsystem should be suspended, false otherwise.

Definition at line 58 of file subsystem_mgr.cxx.

void SGSubsystem::suspend ( ) [virtual]

Suspend operation of this subsystem.

This method instructs the subsystem to suspend sim-time-dependent operations until asked to resume. The update method will still be invoked so that the subsystem can take any non-time-dependent actions, such as updating the display.

It is not an error for the suspend method to be invoked when the subsystem is already suspended; the invocation should simply be ignored.

Reimplemented in SGSubsystemGroup, SGSubsystemMgr, and SGSoundMgr.

Definition at line 52 of file subsystem_mgr.cxx.

void SGSubsystem::unbind ( ) [virtual]

Release the subsystem's property bindings.

This method should release all properties that the subsystem publishes. It will be invoked by FlightGear (not the destructor) just before the subsystem is removed.

Reimplemented in SGSubsystemGroup, SGSubsystemMgr, SGSoundMgr, and SGSoundMgr.

Definition at line 47 of file subsystem_mgr.cxx.

virtual void SGSubsystem::update ( double delta_time_sec ) [pure virtual]

Update the subsystem.

FlightGear invokes this method every time the subsystem should update its state.

Parameters:

delta_time_sec

The delta time, in seconds, since the last update. On first update, delta time will be 0.

Implemented in SGSubsystemGroup, SGSubsystemMgr, SGSoundMgr, and SGSoundMgr.

void SGSubsystem::updateExecutionTime ( double time )

Keep track of execution time.

This method keeps track of timing statistics for each subsystem.

Parameters:

time

execution time in ms of last call.

The documentation for this class was generated from the following files:

SGSubsystem Class Reference

Public Member Functions

Detailed Description

Member Function Documentation