78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
|
# Strucutral Overview
|
||
|
|
|
||
|
|
## Foundation Components
|
||
|
|
|
||
|
|
|
||
|
|
There is a group os basic objects used widely throughout the codebase, which
|
||
|
|
are useful building blocks in all major simulation elements.
|
||
|
|
|
||
|
|
### Properties
|
||
|
|
|
||
|
|
Properties form a hierarchy of named, typed values. The hierarchy can be extended
|
||
|
|
and modified at runtime by aircraft, simulation components and external protocols.
|
||
|
|
|
||
|
|
### Listeners
|
||
|
|
|
||
|
|
Listeners are a callback interface `SGPropertyChangeListener` which can implemented
|
||
|
|
to receive notification when a property is modified, or its children added/removed.
|
||
|
|
Most commonly listeners are used to look for a user input or simulation event
|
||
|
|
changing some value (for example, a switch being turned from on to off), but it's
|
||
|
|
possible to monitor an entire sub-tree of properties.
|
||
|
|
|
||
|
|
It's important than listeners do not block or perform excessive amounts of work, since
|
||
|
|
the code modifying the property may not expect this. If non-trivial work needs to be
|
||
|
|
performed in response to a property changing, the listener should set a dirty flag
|
||
|
|
and a subsystem (etc) should check this in its `update()` method.
|
||
|
|
|
||
|
|
### Tied properties
|
||
|
|
|
||
|
|
Tied properties allow a property to be defined by a C++ memory location (such as a class
|
||
|
|
member variable) or by callback functions implementation the get/set operations. This
|
||
|
|
is very convenient for the implementating code. However, by default it has the
|
||
|
|
problematic side-effect that listeners do not correctly, since they have no way to be
|
||
|
|
notified thst the underlying value (or result of invoking the getter) has changed.
|
||
|
|
|
||
|
|
It is therefore critical, when using tied properties, to _manually_ invoke `fireValueChanged`
|
||
|
|
on dependent proeprties, when updating the internal state producing them. Care should be
|
||
|
|
taken to only fire the change, when the result of the getters would actually change; it is
|
||
|
|
_not_ acceptable to simply call `fireValueChanged` each iteration, since any connected
|
||
|
|
listener will be run at the simulation rate.
|
||
|
|
|
||
|
|
### Conditions
|
||
|
|
|
||
|
|
_Conditions_ are predicates which can be evaluated on demand. They can contain
|
||
|
|
logical operations such as 'and' and 'or', and comparisoms: for example checking that
|
||
|
|
a property is equal to a constant value, or that a property is less than another
|
||
|
|
property.
|
||
|
|
|
||
|
|
Conditions are widely used to drive other state from properties; for example
|
||
|
|
enabling or disabling user-interface in a dialog, or activating an autopilot
|
||
|
|
element.
|
||
|
|
|
||
|
|
### Bindings
|
||
|
|
|
||
|
|
_Bindings_ are a command invocation with associated arguments. In the simplest case
|
||
|
|
this might be invoking the `property-set` command with an argument of 42. At its
|
||
|
|
most complex, the command might invoke a Nasal script, supplied as part of the
|
||
|
|
binding, and substituing a runtime value into the Nasal logic.
|
||
|
|
|
||
|
|
Bindings are typically used in response to user actions, such as a menu item, key
|
||
|
|
press or interacting with a cockpit control, to update some part of the simulator
|
||
|
|
state.
|
||
|
|
|
||
|
|
## Structural Components
|
||
|
|
|
||
|
|
Most code within FlightGear is organized into subsystems. Subsystems are isolated from each other;
|
||
|
|
a well designed subsytem can be added, remove or restarting independently. Many subystems do not
|
||
|
|
full conform to these goals, especially regarding runtime adding and removal, but an increasing
|
||
|
|
number do support it.
|
||
|
|
|
||
|
|
=== Subsystems ===
|
||
|
|
|
||
|
|
=== Commands ===
|
||
|
|
|
||
|
|
|
||
|
|
## Finding data files
|
||
|
|
|
||
|
|
## Subsysterm Lifecycle
|