Howto:Start core development
| This article or section contains out-of-date information
01/2012: I have taken my forum response and copied/pasted it here. Everybody is invited to contribute. While we do have a Volunteer page, we don't currently have a page dedicated to people wanting to contribute to the C++ source code, so this is an attempt to get something like this started.
- 1 How the Project works (Suggested reading!)
- 2 Welcome to FlightGear
- 3 Recent Efforts
- 4 Hacking the C++ code
- 5 Initial advice
- 6 Project architecture
- 7 The source code
- 8 Continuous Integration (CI)
- 9 Patches
- 10 Ongoing efforts
- 11 Issue tracking
- 12 Talking to fellow FlightGear developers
- 13 Flight dynamics
- 14 Important docs
- 15 Getting started
- 16 Some Ideas
- 17 Finally
How the Project works (Suggested reading!)
- [| Flightgear Policy Document briefly covering what will be expected of a contributor]
- [| Other Information to be Aware Of]
- [| Forum article on Flightgear Development]
- How the FlightGear project works
Please see this short essay here: http://flightgear.org/forums/viewtopic.php?f=42&t=15267#p149971
Welcome to FlightGear
Hi, and welcome to FlightGear!
You have probably come here to learn more about implementing new features for FlightGear.
Often, implementing new ideas and features doesn't necessarily require C++ knowledge, FlightGear has become so flexible and powerful that it is increasingly configurable even without touching the C++ source code. This is an important advantage, because building FG from source and finding your away around two fairly complex code bases (i.e. SimGear and FlightGear) can be a daunting task, even for experienced C++ developers.
This isn't to say that C++ / programming knowledge wouldn't be useful though. And if that's where your interests are, you are certainly invited to contribute to the C++ code, too.
Not yet familiar with C++ ?
If you don't yet know what a compiler is, what C++ is or how programming works, you may want to check out Howto: Understand the FlightGear development process.
While learning how to program is definitely possible, learning C++ in particular and becoming familiar with a complex code base like FG/SG does take a certain amount of time. In particular, setting up a working build environment to build FG from source, can be a daunting task for people without any corresponding background knowledge.
If you know for sure, that you want to learn C++, we have a collection of helpful resources here: C++ resources. This includes a bunch of animated screen casts (i.e. video tutorials) on youtube: http://www.youtube.com/view_play_list?p=1D6727247CA35794
Developing without programming is possible and appreciated
For non coding-related ideas on how to to start contributing, there's a dedicated article at Volunteer. Creating new aircraft, cockpits, scenery, instruments, GUI dialogs, etc. doesn't require any programming knowledge at all. If that's what you are interested in, please check out the links at the Developer Portal.
Coding but not in C++ (scripting)
If you are definitely interested in coding, but not in building FlightGear from source (C++), you may want to look into Nasal programming instead, which is FlightGear's built in scripting language, and doesn't require anything besides FlightGear itself.
Many new ideas or features won't require any modifications to the C++ source code at all. You could probably get started and implement many ideas without even touching an IDE or a compiler for quite a while.
That might actually be the easiest route for you to proceed in the beginning. Programming knowledge would obviously still be useful, because Nasal scripting is "real programming", many programming concepts (loops, functions, classes, events etc) you'll encounter in Nasal will seem familiar to people with previous programming experience.
If you are looking for immediate results, Nasal is probably the most promising route - simply because you don't need to look into all the tedious, non-coding related issues. Here's an overview giving you a rough idea about recent Nasal related efforts:
Tutorials & Missions
- set up a gitorious repo with shared access for all contributors 
- helicopter missions (Marius_A )
- Walk View support (Marius_A )
- AI scenarios support (Marius_A )
- NPC support (DFaber )
- self-steering AI vehicles (DFaber )
- extend the framework to support reloading/restarting tutorials at runtime (Marius_A )
- support dynamic mission objectives instead of just static positions Not done  
- investigate supporting Nasal blocks for having multiple instances of an AI/model i.e. for vehicle/NPC control  Not done
- investigate supporting optional Canvas areas for showing mission objectives via MapStructure (Hooray & ludomotico) 
- procedurally-created Canvas GUI dialogs, e.g. for interaction with NPCs and mission briefings Not done
- allowing startup time and environmental settings (weather/METAR string) to be stored as part of the tutorial (e.g. for CAT3 approaches at night time) Not done
|LOD support||LOD handling (i.e. range awareness) needs to be finalized and applied to all existing symbol files|
|New Layer||Navaids (meta layer for VOR, DME, NDB)||Done|
|New Layer||DATA (needs label decluttering)||Not done|
|New Layer||cached GRID (lat/lon) |
|New Layer||tiled maps/SAT (online, )|
|New Controller||interactive/editing |
|New Controller||magnetic (see navdisplay.mfd & unify!)||Not done|
|New Controller||center on acft (see navdisplay.mfd & unify!)||Not done|
|New Controller||acft hdg up (see navdisplay.mfd & unify!)||Not done|
|New Controller||panning/translating (see $FG_ROOT/canvas/map/generic-canvas-dialog.xml)||Not done|
- allow layers to be configured per aircraft ticket 1388
- use switches hash to procedurally create a GUI dialog with buttons for each toggle_action (TFC,CTR,WXR etc) Not done
- make sure that the frameworks with properly with time-warp, sim-rate speed-up and replay Not done
- remove (old) disabled layers Done
- use MapStructure options hash to encode things like nav/comm stuff (anything referencing /instrumentation/) Not done
- make the timer update interval configurable via constructor Not done
- consider adding hooks to generalize those huge conditionals in update() some more Not done
- use foreach() to hide()/show() or setVisible() groups of symbols Not done
- make this more aircraft agnostic by getting rid of 747/Boeing specific assumptions Not done
- unify switch/case|default handling (again, huge conditionals in there) Not done
- on_update() helper should probably support global listeners and timers, too - i.e. via a hash spec ? Not done
- the whole symbol lookup needs to cleaned up (getElementById etc) Not done
- introduce a common "compute" field in the update/predicate hash and make its results available to is_true/false etc Not done
- use io.include to include boeing specific stuff Done (see navdisplay.styles for now)
- NDSourceDriver should be generalized and combined with MapStructure's aircraftpos.controller Not done
- the radio/autopilot listeners need to be set up in the lcontroller file, they're just empty stubs for now Not done
- there are 3 foreach loops in newMFD() setting up symbols currently-we only need ONE: loop 2+3 should be removed and use the loop #1 method Not done
- clean up the ctor and generalize the newMFD() method Not done
- move stuff out of the update() method into the aircraft-specific configuration hash Not done
- generalize/extend on_update() method to support other (global) properties and/or listeners/timers to run predicates Not done
- identify opportunities for improving the framework Not done
- support multiple routes (WPT/RTE), as per the Nasal Flightplan API (Hooray) Not done
- move the config hash out of the navdisplay.mfd file and use io.include instead Not done
- document SVG symbols currently assumed to be available in the ctor Not done
- consider using some of the SGCondition/StateMachine stuff in SG Not done
For example, the tutorial system built into FG is entirely implemented in scripting space, and fully XML-configurable: Tutorials
This means that you can create/modify and improve tutorials just by editing plain text files with any conventional text editor.
There are many more things possible using Nasal, just see the wiki.
And if you find something not being possible in scripting space, you could either fire up your IDE and extend the interpreter or ask another contributor to provide a corresponding patch.
If you are not interested in C++ programming, but also not in Nasal scripting, there's another option: GLSL Shader programming. FlightGear has an extremely powerful "effects" framework and support for running GLSL shaders. While programming shaders for FlightGear doesn't by default require being a C++ developer, being able to build FG from source and knowing C++ can be really helpful though, especially in order to expose new properties to shaders (i.e. improving the property tree <-> shader interface).
Hacking the C++ code
From now on, this article will provide the required pointers to get you started hacking the FlightGear source code. Ideally, you already know C++, or a language very close to it, like C or Java. Also, you should preferably already have experience building programs from source code, otherwise this may seem pretty frustrating if you do this for the first time, simply because FlightGear has meanwhile become a fairly complex code base with many dependencies that need to be satisfied and built in a certain order.
Our advice would be: Start small, start simple, communicate a lot and most importantly release early & often (i.e. use topic branches and commit frequently, and encourage others to provide feedback)
- if you know you want to contribute to the source code, make sure that you are actually able to build FG from source, you can get help using the forum, the mailing list, the issue tracker or live support using IRC chat - we have articles on building FG on various platforms, see Building FlightGear
- read the documentation (wiki, $FG_ROOT/Docs, $FG_SRC/mini-docs)
- it also helps running DoxyGen or Source Navigator to navigate the various source trees
- start making tiny modifications to existing stuff (aircraft, scenery, source code etc)
- try to get to grips with how git works (we have some resources to get you started, using GUI frontends like qgit or a good IDE can be helpful)
- register an account at gitorious
- clone the FG project (SimGear, FlightGear, fgdata)
- browse the issue tracker for bug reports/feature requests, help triage problems, maybe provide patches too (i.e. to mute compiler warnings, to fix memory leaks, fix/add comments, clean up/refactor source code)?
- search the archives (forum and mailing list) for discussions related to your area of interest, these contain often valuable pointers that may save you hours of work
- subscribe to the developers mailing list
- ask for advice/projects there
- check out the wiki for ideas to get started (Watch out, there are plenty of "ideas" listed here, but not all of them are up to date or even "good" ideas, so talk to fellow contributors first before spending any significant amounts of time implementing something)
- coordinate your effort with others, i.e. communicate your intentions early and ask for advice
- release early and often
- don't get frustrated :-)
FlightGear itself consists of a number of different projects and dependencies (libraries), please refer to gitorious for details. Most of FlightGear's supporting code is increasingly getting moved to the "SimGear" project.
Basically, FlightGear depends on SimGear, while SimGear depends on some 3rd party libraries such as OpenSceneGraph (for rendering), plib (utility functions, joystick support, GUI etc), OpenAL (sound) and others like boost.
Once you have satisfied all dependencies and built them in the right order, you can start FlightGear. Note however that FlightGear also has a run time dependency: its so called "base package", i.e. the data package that contains all resources such as scenery, GUI files, aircraft, sounds and so on. We commonly refer to this as "$FG_ROOT".
The FG source tree is commonly referred to as $FG_SRC, while the SimGear source tree is often referred to as $SG_SRC.
A while ago, Jim Wilson posted the following advice on the devel list:
If you are familiar with C++ then you should have no trouble figuring things out. Take a look at the SGSubsystem class. This is the base for all the subsystems in flightgear. The most frequently used functions in this class are the init and the update functions.
Then take time to look at a few subsystems. Generally for most subsystems you can figure that the update function gets called once per frame.
The frame loop is in $FG_SRC/Main.cxx (function mainloop). Here you will see the various subsystem's update calls and the sequence they are done in. What I mean by frame loop is this loop is repeated for each frame (note the rendering down the bottom of it). There is also an event subsystem that is used to schedule calls to update() of certain subsystems on a timer interval.
With this general overview (don't try to understand every line of code yet), you should be able to locate bits of code that you are interested in by perusing the directories of modules. Like I said most subsystems are based on SGSubsystem, so you should be able to locate implementations of init() and update(). Also note that some subsystems are updated by others, so if you don't see the update() called from in the mainloop then do a text search through the modules to find the code that actually does call the update() (look for references to the class you are interested in).
Finally you will want to familiarize yourself with the data that is exposed in the property tree. This is an excellent learning tool. When running FlightGear, bring up the Property browser from the file menu. This property tree is essential for much of the way in which configuration and data output are handled in FlightGear. For example the flight instruments are all configured using xml defined references to values in the property tree in order to position needles, etc. Changing property values can be used to alter the configured behavior of FlightGear at startup using parameters and/or xml declarations, or on the fly using C++ property class functions in the code or from several other interfaces including the property browser (for example: try adjusting the cloud layer settings in the property browser under environment/clouds, you will see the effect right away).
Speaking of instruments, you might want to take a look at how some of the instrumentation configuration (Aircraft/Instrumentation/*.xml files in the base package) in order to get an idea of how different parts of flightgear can be configured to communicate with other parts in a certain way through the property tree. You can also look at the preferences.xml file to see an example of how startup configuration for various subsystems is handled through the property tree.
By browsing the properties and tracing interesting data items to the code they are output from or read by, you can learn a lot about how FlightGear works. When you see something interesting do a text search through the source code for that property name and you will find out how it is utilized.
Welcome aboard and do feel free to post any questions to the list as they come up.
The source code
FlightGear is multi-platform software, that runs on all major versions of MS Windows, Mac OS and Linux. That means, the FlightGear source code also needs to be written and maintained with cross-platform considerations in mind.
The core FlightGear source code itself is largely written in C++, some C and a bunch of helper scripts. FlightGear is based on OpenGL (NOT DirectX !), OSG (OpenSceneGraph) and OpenAL (for sound). An increasing number of features are implemented in scripting space, using a high level scripting language called Nasal, Nasal scripts are maintained in the base package ($FG_ROOT).
The SimGear and FlightGear source trees both make use of the CMake build system as of 2012.
The FlightGear project uses the decentralized source code management system "git" see Git for more info.
The project sources are hosted at sourceforge: https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/
If you know for sure that you'd like to fiddle with the core source code, you'll inevitably need to be able build FG from source, this is also documented in our wiki, a more recent article is to be found here: http://wiki.flightgear.org/Howto:_Build_FlightGear_with_NetBeans_using_CMake
You can find tutorials for different platforms/OS at the end of the article.
Continuous Integration (CI)
For CI purposes, there's a dedicated build server running which rebuilds the FlightGear sources for a handful of important platforms. The server provides a simple and quick overview, it can be found here: http://build.flightgear.org:8080/
Please see FlightGear Build Server for more information.
Regarding patches, please see: Submitting Patches.
Note that this article is meanwhile somewhat deprecated and these days using gitorious (and filing merge requests there) is pretty much encouraged. If your patch is related to a previously reported bug/defect, you can obviously also use the issue tracker (see below).
In general, the FlightGear gitorious project is the entry point for new developers.
Some more recommendations can be found at Recommended Project Policies.
In general, it is always a good idea to clone the FG repositories (i.e. SimGear, FlightGear and FGData) and start working on your own branch there. This will enable fellow contributors to easily keep track of your work, so that they can test your changes and provide feedback as required.
To send patches upstream, gitorious merge requests are recommended. The details of which are covered at Merge request.
A list of active FlightGear core developers is to be found at FlightGear Core developers.
Anybody working on FG's source code, should be aware of the FGViewer trend (decoupling the viewer from the simulation using a headless mode 1) to improve frame rate and latencies, but 2) also to support distributed multi-screen setups) and also the long-term goal to use OSG's CompositeViewer for all of the FG views - so modifications to the existing viewer in $FG_SRC/Viewer should probbaly keep these things in mind to align well with other ongoing developments: http://wiki.flightgear.org/Howto:Use_a_Camera_View_in_an_Instrument#osgViewer::CompositeViewer
An old PDF describing some of the challenges that FlightGear developers are trying to solve through HLA/CIGI adoption can be found at: http://wiki.flightgear.org/flightgear_wiki/images/1/1e/New_FG_architecture.pdf
The FlightGear state of all HLA things is documented at: http://wiki.flightgear.org/FlightGear_HLA_support_(High_Level_Architecture)
Introductory HLA resources are collected at: http://wiki.flightgear.org/Developing_with_HLA#Resources
In developer's terms, that mostly boils down to:
- expect more and more scenery functionality to be procedurally added (e.g. runways, taxiways, whole airports)
- expect more and more viewer functionality to be decoupled from the simulator (fgviewer being the prototype here)
- expect more and more viewer/GUI features to be made optional through a FlightGear Headless mode during startup
- expect the 2D rendering backend (GUI, instruments, HUDs etc) to be increasingly unified through the Canvas system
- expect FGPanel standalone panel rendering functionality to be merged back into the main fgfs code base, provided through FGViewer
- expect more work towards better system-wide reinit/reset support: http://wiki.flightgear.org/Reset_%26_re-init
- expect more and more launcher features to be integrated and provided as part of FlightGear 
- expect FDMs to become re-initializable at runtime, expect support for multiple FDMs per session
- expect more subsystem to become re-initializable at runtime, so that they can be dynamically enabled/disabled to facilitate the fgviewer and headless efforts: http://wiki.flightgear.org/FlightGear_Run_Levels
- expect more and and more mainloop subsystems to eventually become standalone threads/processes (that is, HLA federates) (FDM, AI traffic, scripting etc) to guarantee better viewer performance
- expect the existing multiplayer system to be completely phased out and replaced by HLA
- expect multi-instance slaving to be formalized and reimplemented through FGViewer and HLA
- expect Nasal scripting integration to be increasingly decoupled from the fgfs main loop
- expect OSG CompositeViewer to be eventually adopted (almost certainly not during the next 12 months though)
Basically, help facilitate these change by at least not making these things more difficult through your own code
For doxygen docs, see: http://docs.freeflightsim.org/
In less broader (and more outdated) terms, a list of the latest development efforts can be found at http://wiki.flightgear.org/Category:Core_development_projects If you have anything to add, please feel free to create a new wiki article. Also, contributing such news to the FlightGear newsletter is another good idea.
If you are looking for ideas to get involved one way or another, some of the more long-term issues and most annoying glitches are discussed at Request for comments.
However, please take everything you'll find there with a grain of salt, because many of these articles haven't been updated over the years, so what may have seemed like a great idea 2-3 years ago, may already be depreciated meanwhile. On the other hand, those articles may still help you get a better understanding of architectural issues. In case of doubt, please get in touch with fellow developers.
Also, there's another outdated category titled "Code Cleanup": http://wiki.flightgear.org/Category:Code_Cleanup
Another option would be taking a look at the "Google Summer of Code" category which also lists project ideas collected over the years: GSoC: Candidate Projects. We also have a separate sub forum for GSoC here: http://flightgear.org/forums/viewforum.php?f=38
In other words: pick your poison :)
Ideas (feature requests actually) and bug reports are ideally reported using the issue tracker here: http://flightgear-bugs.googlecode.com/
Please make sure to first search the issue tracker before possibly reporting a dupe, thanks!
Bug reports should ideally be accompanied with a test case to reproduce an issue, but also a backtrace, see: Howto:Debugging FlightGear Crashes#Debugging Segfaults & Obtaining Backtraces.
This is also an excellent place to get started helping and contributing to FG, i.e. by triaging bug reports, discussing feature requests, posting patches or finding new ideas to work on. This is also a very good place to get in touch with other core developers.
Also, if you have some new ideas in mind, and would like to extend FlightGear in some way, it's a good idea to use the issue tracker to make feature requests. Fellow FlightGear developers will be able to provide feedback regarding your feature request and tell you directly if and how exactly your idea can be best implemented.
For example, to view a list of feature requests that were accepted by other core developers, just go to: https://code.google.com/p/flightgear-bugs/issues/list?can=2&q=FeatureRequest%20status%3Aaccepted
Talking to fellow FlightGear developers
Most core development related discussions are handled using the developers mailing list: http://www.flightgear.org/mail.html
There's a fully searchable archive available here: http://email@example.com/
In addition, the FlightGear forums are increasingly used for interesting development related discussions, please note though that these are usually not specific to FG core development, but instead general development (aircraft, scenery, shaders, scripting): http://flightgear.org/forums/
If there's something particular that you are interested in, it's always a good idea to search these resources (wiki, forum, mailing list) to find related discussions.
Improving the flight dynamics often doesn't require any C++ changes, FlightGear provides a powerful FDM interface and different FDM engines (namely JSBSim and YaSim), both of which are entirely configurable by using XML files.
For JSBSim, please see: http://jsbsim.sourceforge.net/
There's a wealth of documentation to get you started available in $FG_ROOT/Docs
API docs auto generated from source are at http://api-docs.freeflightsim.org/
Even more documentation can be found in our wiki, here: http://wiki.flightgear.org/
The wiki is divided into different "portals", you'll probably be interested in the developers portal here: http://wiki.flightgear.org/Portal:Developer
You are obviously invited to start your own wiki articles, in order to document your projects or help improving existing documentation. Also, some core developers actually use the wiki to post their own development roadmaps. For example, see: Plan-zakalawe or Project Rembrandt.
Don't worry if your C++ experience should be dated: In many parts, the FlightGear code base is still somewhat archaic and not very modern, so you won't find too many occurrences of really advanced C++ concepts, in many places you'll just find simple "C with classes" uses, some STL and inheritance. But complex C++ features (such as advanced templates or meta-programming are not too common actually).
One of the simplest ways to add new features to FlightGear is adding new commands to it, so called "fgcommands" (i.e. "FlightGear commands"). For additional information, please see this tutorial: Howto: Add new fgcommands to FlightGear.
If you need to read up on something programming related, such as C++, the STL, OpenGL, shaders etc, the wiki has plenty of programming resources to get you started: Resources.
The SimGear code base is somewhat less archaic and more modern actually. And if you are interested in contributing to the OpenGL/SceneGraph department, you'll inevitably need to look into OpenSceneGraph (OSG), too - which really is "modern C++".
SimGear is fairly well-maintained code base that contains a fair amount of doxygen comments, that means that it's easy to create doxygen documentation for SimGear. For example, see: http://api-docs.freeflightsim.org/simgear/
Note that, at the time of reading, this may be outdated, so if you are interested in using the latest doxygen docs, you are well advised to run doxygen against your own latest simgear clone.
Also, you can get a fair amount of information out of the FG sources by running them through doxygen, too.
Plain C ? (Nasal)
If your C++ is rusty and you'd just like to get started quickly, there are also certain FG components that are strictly (largely) pure C, the Nasal interpreter is just one example (Nasal is FlightGear's built in scripting language): http://wiki.flightgear.org/Nasal_scripting_language
The Nasal interpreter is part of the SimGear project, and can be found in $SG_SRC/nasal: https://sourceforge.net/p/flightgear/simgear/ci/next/tree/trees/next/simgear/nasal
The longest-standing issue related to Nasal scripting is fixing its Garbage Collector (GC) to become generational, incremental or even concurrent, this is to reduce main loop impact (frame rate & frame spacing), see How the Nasal GC works to learn more. Almost certainly, we're going to adopt an existing GC library, or even implement an interface to experiment with different GC schemes, and allow those to be selected at startup.
Adding new extension functions to the built-in Nasal interpreter is documented here: Howto: Extend Nasal.
None of this requires any C++ knowledge!
Only the scripting interface connecting the Nasal interpreter and FlightGear is implemented in C++, it can be found in $FG_SRC/Scripting
Basically, the scripting interface implements a custom SGSubsystem, so that the Nasal interpreter can be run as a FlightGear system. In addition, all FlightGear-specific extension functions are to be found there. Increasingly, this folder also contains wrappers to map FlightGear classes to Nasal space in an OOP fashion using the Nasal/CppBind framework, so that not just functions, but full "objects" are provided, which are computed lazily. If that's what you are interested in, you should take a look at the NasalPositioned_cppbind.cxx source code, which demonstrates how this is done.
In other words, even without knowing C++, you can contribute to FlightGear core by extending the Nasal system. If you have some specific project in mind, you could probably implement it largely in scripting space using Nasal and only augment it as required with new extension functions in C space.
Once you have found an area you are interested in, you can search the wiki, archives (mailing list and forums) or the issue tracker to find suitable projects to work on, for example: http://code.google.com/p/flightgear-bugs/issues/list?can=2&q=nasal&colspec=ID+Type+Status+Priority+Summary+Aircraft+Milestone&cells=tiles
Talk about your plans
Before you start any serious efforts, please make sure to get in touch with other contributors. Ideally, using the developers mailing list or the forum. This is to ensure that others know about your plans, i.e. to avoid duplicate work, but also conflicting approaches.
Often, FlightGear developers have certain ideas and plans for their projects, so it's good to coordinate your ideas with fellow contributors. In addition, you can get valuable feedback from experienced contributors this way, which may save you countless hours of time and lots of frustration.
You may even find people interested in your idea and teaming up with you!
Another straightforward way to get started adding C++ code is using the Nasal/CppBind framework to expose built-in C++ classes to Nasal and enable base package contributors to make use of these, without bugging core developers to implement certain features directly. For C++ developers it is generally less time consuming (and often more rewarding) to implement abstract frameworks and infrastructure, rather than individual features.
While the number of core developers has been decreasing during the last 12-18 months, we do have an increasing number of base package developers, so implementing generic hooks for them makes sense because core developers cannot possibly implement each requested feature.
Adding new subsystems
If you are interested in adding new subsystems to FG, you may want to check out this: Howto:Create new subsystems.
Also, we have a step-by-step guide illustrating how a new system can be added to FlightGear, going into more detail. See Howto:Create a 2D drawing API for FlightGear
The property tree
The FlightGear property tree is documented here: Howto:Work with the Property Tree API
Additional Scripting Bindings
FlightGear's built-in Nasal scripting language comes with a set of standard libraries, and can be extended using FlightGear specific APIs.
Exposing simulator internals to scripting space is a fairly common and useful thing, because it enables base package developers to access these internals without having to build FlightGear from source, so the barrier to entry is significantly lower and we've seen an increasing number of novel features purely implemented in scripting space, due to powerful APIs being available to aircraft developers and other base package developers.
Until FlightGear 2.8, the Nasal scripting engine only provided a C API to expose such hooks/bindings to scripting space or to expose scripting space data structures back to C/C++.
Unlike the core Nasal engine itself (which is C), FlightGear however is mostly written and being developed in C++. For quite a while, that meant that the Nasal APIs were a bit low-level, and sometimes also awkward to use when making functions, data structures or objects accessible between C++ and Nasal.
Thanks to development on Tom's Canvas system, there's now a new bindings framework to be found in $SG_SRC/simgear/nasal/cppbind. This is fully object oriented and supports modern C++ features by operating through classes and methods with full STL support, abstracting most common operations away.
After working through the Nasal/CppBind article, some of the more useful things to play with in the beginning, would be exposing additional SG/FG classes to Nasal space, such as for example:
- SGPath Done (by TheTom)
- SGCondition Done (by TheTom) flightgear/flightgear/1b55ab5f4032c6f3f1a4d07c0b9babd3744f1c37 commit view
Work in Progress
- SGPropertyChangeListener Pending (suggested by Zakalawe & TheTom) 
|This and using maketimer instead of settimer should reduce the number of leaked resources a lot, because you would not be able to accidentally leak listeners/timers anymore.
— Thomas Geymayer (2014-11-22). [Flightgear-devel] RFC: Nasal ghosts and garbage collection.
(powered by Instant-Cquotes)
|Note This is a summary of all discussions about exposing the autopilot/property-rule system (there are certain Nasal GC issues, so that we ask people not to implement FDM-coupled Nasal code like autopilots): this would be the best way to decrease the amount of Canvas-related Nasal code, i.e. by using property-rules for animation purposes, as per Torsten's RBAR EFIS  and TheTom's system-modeling plans.|
|I would prefer to do this in an XML filter in the generic autopilot helpers - definitely not in Nasal. It can be done in C++ if strictly required but then we need way to disable it for people who want different filtering.
— James Turner (2015-04-03). Re: [Flightgear-devel] Route manager: waypoint smoothing.
(powered by Instant-Cquotes)
|I vote for #3: avoid *any* Nasal in the fast simulation [FDM] loop. Nasal execution is slow and non-deterministic. Running it in the fast simulation loop is the last thing we want.
|Concerning your original issue on implementing an autopilot: a much better way to do it is to avoid Nasal for the actual autopilot controller elements (numeric computation). Instead, use XML "autopilot" rules for the filter, gain, damper, integrator elements: http://wiki.flightgear.org/Autopilot_Configuration_Reference
You can then use Nasal for the high level stuff, and enable/disable/switch the individual controller elements (e.g. in order to automatically switch the autopilot mode when capturing the ILS).
|I agree with your main point that xml-configured hard-coded filters are the right way to implement and autopilot, and I also agree that in general low-level multi-purpose workhorse code should be C++ whereas Nasal is more suitable for the numerically cheap high-level specific functions.
— Renk Thorsten (2012-08-30). Re: [Flightgear-devel] Running Nasal at simulation rate.
(powered by Instant-Cquotes)
|I'd strongly agree with Thorsten here. It's nothing against Nasal from me - I've not even used it - but creating an autopilot (or any GNC or system model, for that matter) can be done very effectively with discrete objects such as summers, gains, controllers, filters, switches, etc., much as JSBSim has done with the system components. This is a standard approach in industry as Thorsten mentions as exemplified by Mathwork's $imulink product.
Scilab/Scicos is similar in concept. Control system topologies are often diagrammed in a way that can lead to a one-to-one correspondence between a block and a control system object that can be referenced in an XML file, if the control system component library has been defined properly. This, again, is the way that JSBSim has approached the solution. Some benefits to such an approach include (IMHO) better testability, more predictability, and easier interface (someday) with a GUI tool, should one materialize. The downside is that XML can be verbose, but it's a price I've come to accept.
— Jon S. Berndt (2012-08-30). Re: [Flightgear-devel] Running Nasal at simulation rate.
(powered by Instant-Cquotes)
|I have recently committed some code to allow runtime loading of property rules and have a Nasal binding for that in mind.
|The more I think about it, the more I am leaning towards unifying the different system modeling blocks in the C++ core under a generic interface that is exposed (or linked in some way) to Nasal. Think the PID controller, the different filters, flip-flops, etc. They are not substantially different to the basic bricks I am writing...The basic idea would be to detach those blocks from their specific application (autopilot, for example) and refactor them into an independent library with bindings in Nasal and a similar interface to what I have been showing so far. The end result would be quite simulinkish in flavour. It is already starting to smell a bit to that actually... :D
An architecture like that would eventually enable three possible approaches to system modeling: low level C++, static xml driving C++ underneath and fully scripted Nasal.
— galvedro (Tue Nov 05). Re: A general approach to systems modeling in Nasal.
(powered by Instant-Cquotes)
|Regarding things like the PID controller code, its developer/maintainer (Torsten) was actually planning on making this stuff accessible from Nasal, just to prevent scripters from implementing APs in Nasal (due to garbage collection issues) - so that should be a no-brainer actually, and such work should be appreciated
— Hooray (Tue Nov 05). Re: A general approach to systems modeling in Nasal.
(powered by Instant-Cquotes)
|there's an extremely powerful and flexible autopilot system in FG that is entirely XML configurable: Autopilot
There's also a very powerful route manager. Please note however, that there's currently no support for AI traffic to directly make use of the autopilot system or the route manager, so you need to come up with your own infrastructure in scripting space.
|Note however that scripted AI traffic cannot currently make use of any hard-coded FDMs/AP/RM functionality (JSBSim/YaSim), instead you need to come up with your own "pseudo systems" in scripting space unfortunately.
|The AI traffic system has its own "route manager" system which is currently not yet compatible with the rest of FG unfortunately. But there are plans in place to fix this eventually: http://flightgear.org/forums/viewtopic. ... 0&#p134970
|At the moment, Durk has already implemented his own "custom" AI FDM logic, exactly like David predicted a decade ago
|You can probably find 50+ postings by long term contributors suggesting that AI traffic with FDM support would be a good idea: An_Integrated_AI_Traffic_System#FDM_driven_AI_Traffic
| if you wanted to equip your AI traffic with a working route manager, autopilot or even FDM, you would also need to instantiate these subsystems dynamically
|ne thing I thing I want to achieve with this changes is to make the Nasal props API more similar to its C++ counterpart as this makes it easier to use if you are using both the C++ and the Nasal API. Also someday I want to refactor nasal-props.cpp to use cppbind, where I want to export as much methods as possible with exactly the same signature than in C++. Especially if using properties seldom (eg. only for initialiation) the relative versions are probably even faster, as the Nasal overhead is lower. Eg. consider the following Nasal code used to initialize some module: var cfg = props.globals.getNode("/my/config/root", 1); var x = cfg.getDoubleValue("x"); var do_it = cfg.getBoolValue("do_it"); Using getprop on the one hand does not allow getting a property converted to a given type and on the other hand is tedious to use for more than one property, as one has to assemble the according property paths (which is definitely less efficient than using a relative method).
— Thomas Geymayer (Apr 14th, 2013). Re: [Flightgear-devel] Nasal props API relative path support.
(powered by Instant-Cquotes)
- environmental sounds 
- simgear::PropertyBasedElement (background/motivation)
- for better diagnostics, and better end-user bug reports, we could consider exposing a cross-platform process and system utilities module via Nasal/CppBind, such as e.g. SIGAR (Windows, MacOS & BSD/Unix) Not done
- Airways/Airspace boundaries don't seem to be exposed via NasalPositioned currently? 
- FGProtocol, to implement I/O protocols via Nasal (and help solve ticket 396 and support AJAX, REST, JSON or WebSockets)    (stubs available at gitorious/fg/hoorays-flightgear/topics/cppbind-fgprotocol).
- the loglist/SG_LOG() logging buffer machinery 
- expose VoiceSynthesizer/FLITE TTS to Nasal to get rid of ATC chatter  Not done
- the SGSubsystem interface to register scripted SGSubsystems
- flight path history  Done (by TheTom)
- the flight recorder system (replay buffers) Not done
- State machines e.g. to help clean up the ND code 
- exposing the sound manager, so that scripts can directly play audio files 
- exposing the random buildings system  Pending  
- There's also a pending feature request (ticket 619) to implement USB-HID support .
- ESRI shapelib? 
|When we have vector road data at runtime, we can do the following:
— James Turner (2014-11-21). Re: [Flightgear-devel] Future city terrain strategy.
(powered by Instant-Cquotes)
- effects framework ?
- Howto:Using OpenCL in FlightGear
- Nasal/HLA bindings, so that we can run certain scripts as HLA federates outside the fgfs process space (such as bombable or local weather)
|Specifically, there are some C++ data structures that still need to be exposed to Nasal via cppbind so that we can implement features available in the Map dialog and the hard-coded ND
| Note Before working on anything related, please do get in touch with other contributors to ensure that this list is still up-to-date.
For more technical Nasal questions (C API, internals etc), you'll probably want to refer to Philosopher, TheTom, Zakalawe or Hooray on the forum - TheTom and Zakalawe can also provide help on using cppbind, having both used it extensively during the last months.
This is a long-standing feature request, for details, please see CompositeViewer Support.
World Scenery 3.0
The Terragear maintainers are looking for volunteers to help with development on the next world scenery project. If you've ever wondered how a full 3D model of earth can be generated from raw data, now is your chance. See the plan at World Scenery 3.0 roadmap.
|Note Also see |
|actually the entire JPEGFactory option could likely be removed, and replaced with using the osgDB Image plugins to create a JPEG or PNG. And then it wouldn't need to be a CMake option at all. If anyone would like to attempt this, please ask and I can suggest where to start, it's a nice small project
— James Turner
|It's turned off for build reasons, not because it's new or untested. I believe
many people have used it exactly the way you describe. If you encounter
problems, they should be easy to fix and patches are welcome!
(The build reasons could actually be solved by using OSGDB to write out the
files instead of using libjpeg directly - this would mean the feature could be
enabled all the time, i.e removed from CMake, and also we could write out PNGs
instead of JPEGs if desired - if you have any interested in doing this, I can
point you at examples since the screenshot code was converted to do the same
thing recently -it's probably a couple of hours hacking at most)
— James Turner
|If someone decides to jump into this, another feature that would be cool
would be to stream the display out as a video stream which could then be
played by any number of video players on a remote computer (like mplayer.)
ffmpeg probably would provide library support to make this pretty
straightforward, but I haven't had a chance to dive in and see how
easy/hard it would be.
One area where this feature could be useful is in UAV research and
simulation where you'd like to emulate a live video feed back to a ground
station. It could also be fun for sharing/broadcasting your simulator
session and probably could be made to work with a web video server.
— Curtis Olson
|I wanted to capture the FG imagery and
stream it over the web... (or some similar solution)
|I've seen other
apps that can do this so I know it's technically possible, and I imagine
not too much coding once you figure out the magic to make it happen.
— Curtis Olson
|VLC does this better than ffmpeg, so it's probably a good idea to study it's
codebase for streaming code. Also, MJPEG is nice, but as a container I'd
choose Ogg/Theora instead of H264 since they're entirely open.
|Note if you want actual good performance from this system, there's much smarter
things that could be done, such as grabbing the frame buffer each normal
rendering frame, instead of re-rendering the scene each time an HTTP get is
received. That would need much more drastic changes to the system however.
|And obviously it does require that cmake finds the
JPEG includes and libraries... I had earlier compiled
and installed jpeg-9 into my 3rdParty folder...
This dependency would go away if OSGDB was used,
as James mentioned, but then JPEG would probably have
to be found during the OSG build, unless OSG has
alternate built-in jpeg code... not sure...
Thereafter, running fgfs.exe with --jpg-httpd=1234
worked fine by putting http://localhost:1234 is a
browser, and bingo had a jpg image of the screen
in the browser ;=)) cool stuff...
Of course it is a 'static' image, and had to refresh
to get updated images of the flight... or an extension
added to provide an actual video feed as Curt mentioned...
So I would say it worked as advertised
Also see: ticket 924.
We could probably also look at using the Canvas system with some additional hooks, i.e. for getting a handle to the osg::Image, so that it can be serialized through Nasal and some cppbind glue, that would make it possible to depreciate the JPEGFactory code and use the Canvas system instead (i.e. unifying the 2d rendering backend).
Being able to render camera views to a canvas texture has been previously requested a number of times, e.g. for implementing "mirrors" or tail cameras (A380)     , and getting a handle to the buffer for serialization purposes would also allow us to reimplement the screenshot feature on top of canvas/Nasal, and even serve live image data through the httpd component.
- James Turner (Tue, 11 Jun 2013 22:40:38 -0700). Re: [Flightgear-devel] Enabling JPEG factory causes fgfs/GIT to fail compiling.
- James Turner (Tue, 17 Sep 2013 04:17:15 -0700). Re: [Flightgear-devel] --jpg-httpd command line option.
- Curtis Olson (Tue, 17 Sep 2013 11:51:00 -0700). Re: [Flightgear-devel] --jpg-httpd command line option.
- (). .
- Curtis Olson (Tue, 17 Sep 2013 11:51:00 -0700). Re: [Flightgear-devel] --jpg-httpd command line option.
- (). .
- (). .
- (). .
...please don't get discouraged if you shouldn't get too much feedback in the beginning, probably many contributors are busy preparing the next release: http://wiki.flightgear.org/Release_plan
Lack of feedback doesn't necessarily mean that nobody likes your project or your ideas, probably it just means that you need to do some networking to get in touch with other contributors.
Usually, getting involved in the forum, the issue tracker or in merge request discussions via gitorious is a good idea to familiarize yourself with the project. Please keep in mind that we get to see plenty of people each month announcing some fancy new FlightGear-related projects, so your signal/noise ratio is pretty important here. It's pretty likely that the type of feedback you get will be improving once you start contributing patches and help triage bug reports.
People announcing that they want to work on FlightGear, without knowing C/C++ or without having ever built software from source, obviously have to face a steep learning curve, and we are aware of that.
Sometimes, it may even take good ideas a while to be recognized as such, even if suggested by seasoned long-term contributors. So, please don't interpret lack of feedback as a general lack of interest.