Howto:Start core development

From FlightGear wiki
Jump to: navigation, search
This article or section contains out-of-date information

Please help improve this article by updating it. There may be additional information on the talk page.


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.

How the Project works (Suggested reading!)

Please see this short essay here: http://flightgear.org/forums/viewtopic.php?f=42&t=15267#p149971

Also see Implementing new features for FlightGear

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.

The "Nasal" programming language built into FG is syntactically very close to C and C++, it looks a lot like JavaScript - so you could run your own code inside FG without having to build FG from source, no need for compilers or an IDE. FlightGear IS the run time environment for Nasal code.

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:


Recent Efforts

Tutorials & Missions

  • set up a gitorious repo with shared access for all contributors [1] 30}% completed
  • helicopter missions 70}% completed (Marius_A [2])
  • Walk View support 80}% completed (Marius_A [3])
  • AI scenarios support 10}% completed (Marius_A [4])
  • NPC support 70}% completed (DFaber [5])
  • self-steering AI vehicles 50}% completed (DFaber [6])
  • extend the framework to support reloading/restarting tutorials at runtime Priority 50}% completed (Marius_A [7])
  • support dynamic mission objectives instead of just static positions Not done Not done [8] [9]
  • investigate supporting Nasal blocks for having multiple instances of an AI/model i.e. for vehicle/NPC control [10] Not done Not done
  • investigate supporting optional Canvas areas for showing mission objectives via MapStructure (Hooray & ludomotico[11]) 30}% completed [12]
  • procedurally-created Canvas GUI dialogs, e.g. for interaction with NPCs and mission briefings Not done 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 Not done


Canvas MapStructure

Type Work item Progress
Layer FIX 80}% completed
LOD support LOD handling (i.e. range awareness) needs to be finalized and applied to all existing symbol files 60}% completed
New Layer Navaids (meta layer for VOR, DME, NDB) Done Done
Traffic Layer TFC 90}% completed
New Layer DATA (needs label decluttering[13]) Not done Not done
New Layer HISTORY Done Done
New Layer cached GRID (lat/lon) [14] 20}% completed
New Layer tiled maps/SAT (online[15], [16]) 10}% completed
Controller zoom Done Done
New Controller interactive/editing [17] 10}% completed
New Controller magnetic (see navdisplay.mfd & unify!) Not done Not done
New Controller center on acft (see navdisplay.mfd & unify!) Not done Not done
New Controller acft hdg up (see navdisplay.mfd & unify!) Not done Not done
New Controller panning/translating (see $FG_ROOT/canvas/map/generic-canvas-dialog.xml) Not done Not done


Canvas NavDisplay

  • 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 Not done
  • make sure that the frameworks with properly with time-warp, sim-rate speed-up and replay Not done Not done
  • remove (old) disabled layers Done Done
  • use MapStructure options hash to encode things like nav/comm stuff (anything referencing /instrumentation/) Not done Not done
  • make the timer update interval configurable via constructor Not done Not done
  • consider adding hooks to generalize those huge conditionals in update() some more Not done Not done
  • use foreach() to hide()/show() or setVisible() groups of symbols Not done Not done
  • make this more aircraft agnostic by getting rid of 747/Boeing specific assumptions Not done Not done
  • unify switch/case|default handling (again, huge conditionals in there) Not done Not done
  • on_update() helper should probably support global listeners and timers, too - i.e. via a hash spec ? Not done Not done
  • the whole symbol lookup needs to cleaned up (getElementById etc) Not done Not done
  • introduce a common "compute" field in the update/predicate hash and make its results available to is_true/false etc Not done Not done
  • use io.include to include boeing specific stuffDone Done (see navdisplay.styles for now)
  • NDSourceDriver should be generalized and combined with MapStructure's aircraftpos.controller Not done Not done
  • the radio/autopilot listeners need to be set up in the lcontroller file, they're just empty stubs for now Not done 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 Not done
  • clean up the ctor and generalize the newMFD() method Not done Not done
  • move stuff out of the update() method into the aircraft-specific configuration hash Not done Not done
  • generalize/extend on_update() method to support other (global) properties and/or listeners/timers to run predicates Not done Not done
  • identify opportunities for improving the framework Not done Not done
  • support multiple routes (WPT/RTE), as per the Nasal Flightplan API (Hooray) Not done Not done
  • move the config hash out of the navdisplay.mfd file and use io.include instead Not done Not done
  • document SVG symbols currently assumed to be available in the ctor Not done Not done
  • consider using some of the SGCondition/StateMachine stuff in SG Not done 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.

Shader programming

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.

Initial advice

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 :-)
  • enjoy!

Project architecture

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.

Patches

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.

Ongoing efforts

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 [18]
  • 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 :)

Issue tracking

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://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/

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.

Flight dynamics

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/

Important docs

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.

FlightGear

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.

Programming resources

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.

SimGear

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.

There's also a separate wiki article providing a list of known issues related to the Nasal interpreter itself: Improving Nasal, specifically see Nasal Maintenance.

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.

Getting started

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!

Scripting Hooks

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

Some Ideas

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:

Done

Work in Progress

  • SGPropertyChangeListener Pending Pending (suggested by Zakalawe & TheTom) [19]
Cquote1.png 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)
Cquote2.png

Autopilot/Property Rules

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 [20] and TheTom's system-modeling plans.
Cquote1.png The quantity of details and system modeling that goes in to covering all the aircraft of the world is impossibly complex. The idea is to put as much support for common/shared systems in C++ as we can and then make it possible to stitch these systems and details together and configure them with xml in a wide variety of ways to create aircraft. But we can never anticipate every system in use, and we can't anticipate the level of detail or feature set that every aircraft developer might want to implement or experiment with, and even if we could there would be no way to model everything in the world in a single application. Nasal gives a lot of flexibility to cover those unanticipated gaps and it allows aircraft developers to push in new areas ahead of the C++ coverage. Now in many cases, aircraft developers were happy with the nasal implementation and called it good enough. Many aircraft developers have become proficient and comfortable in nasal and prefer doing their work there.
— curt (Dec 16th, 2015). Re: Military simulation (from Su-15 Screenshots).
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png Nasal does have an advantage in that it is easier to tailor to specific requirements. So, providing that the CPU overhead is acceptable, this may be a preferable method for many aircraft.A C++ coded module is fixed in stone, but nasal and xml modules are far easier to modify/overload on a per-aircraft basis.As I am modelling a 1960´s military bomber I have quite a number of (very) aircraft specific requirements which are not met by the current RM/GPS code which is targeted at present day commercial usage.
— Alant (Aug 19th, 2015). Re: Route manager leg modes.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png 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)
Cquote2.png
Cquote1.png 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.
Cquote2.png
Cquote1.png 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).


Cquote2.png
Cquote1.png This is also how such things are done in the real world: controllers aren't implemented in imperative programming languages these days - especially not in scripting languages. People use model-based design and connect controller elements - using graphical tools like MATLAB/Simulink. Obviously, FG is missing a graphical interface to specify the controller rules - but the idea of specifying through XML is the same and specification is straight forward.
Cquote2.png
Cquote1.png 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)
Cquote2.png
Cquote1.png it should basically resemble the C++ 3D animation system and be invisible (enough) that it could easily be replaced with more C++ should we need more performance (or just 'cause). Exposing SGExpression to Nasal would be helpful soon but not necessary yet.
— Philosopher (Sat Aug 16).  animations.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png Given that a very simple animation system would mainly need to deal with "events/triggers" (i.e. timers & listeners) and "actions", we might even be able to reuse some of galvedro's sophisticated failure management modules, because those already deal with both concepts via the property tree (sent a heads-up to him for some feedback).
— Hooray (Sat Aug 16). Re: .
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png 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)
Cquote2.png


Cquote1.png I have recently committed some code to allow runtime loading of property rules and have a Nasal binding for that in mind.
— Torsten (Thu Feb 02). Re: 2 Questions: vacuum & electrical.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png 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)
Cquote2.png
Cquote1.png 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
Cquote2.png
Cquote1.png 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.


— Hooray (Thu Jan 05). Re: Multiple intelligent flyers.
(powered by Instant-Cquotes)
Cquote2.png


Cquote1.png 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.
— Hooray (Tue Jan 03). Re: Multiple intelligent flyers.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png 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
— Hooray (Thu Jan 05). Re: Multiple intelligent flyers.
(powered by Instant-Cquotes)
Cquote2.png


Cquote1.png At the moment, Durk has already implemented his own "custom" AI FDM logic, exactly like David predicted a decade ago
— Hooray (Thu Mar 15). Re: [SUGGESTION] Multi-core FlightGear support.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png 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
— Hooray (Thu Mar 15). Re: [SUGGESTION] Multi-core FlightGear support.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png When you then take into account that you will probably not need to run the AI traffic FDM at a rate of 120 hz (the FlightGear default), but much more likely at 1-5 hz (at most), you should be able to multiplex at least 20-30 different aircraft onto one dedicated FDM thread (or process).


Thus, the problem lies in the integration part and not the lack of computing power: AI traffic is already the component that accounts for many reported performance bottlenecks and unfortunately the "solution" has often be to disable AI traffic or at least reduce traffic complexity.
Before these issues are resolved, we are unlikely to see real FDMs being supported to simulate AI traffic, even though that would simplify many things in one go (e.g. any aircraft could be used as an AI aircraft and so AI aircraft could also benefit from other systems such as the autopilot or route manager).


— Hooray (Wed Feb 24). Re: "Sophisticated AI aircraft" ... ?.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png you would need to hack the autopilot code so that autopilot configurations can be loaded and created dynamically. At the moment, the autopilot code makes the fixed assumption that there's only a single "main aircraft", so it doesn't know about more than one aircraft.
— Hooray (Thu Jan 05). Re: Multiple intelligent flyers.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png 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
— Hooray (Thu Jan 05). Re: Multiple intelligent flyers.
(powered by Instant-Cquotes)
Cquote2.png

props.nas

Cquote1.png 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)
Cquote2.png

Candidates

Cquote1.png When we have vector road data at runtime, we can do the following:
  • render it in moving-map displays - either real ones (Garmin G1000 / G430) or the map dialog
  • use it to drive building outline creation as Thomas was suggesting
  • animate traffic on the roads, as point lights at night or even meshes in daytime
    (the important one...)
  • generate tile overlay textures dynamically (and based on view distance) to show the roads on the terrain surface. (And the detail of this texture can include road markings / borders based on distance from the viewer / view angle / etc)

— James Turner (2014-11-21). Re: [Flightgear-devel] Future city terrain strategy.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png 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

Canvas_GUI#PUI_Widgets


— Hooray (Tue Jun 24). Phasing out MapWidget post 3.2.
(powered by Instant-Cquotes)
Cquote2.png
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.


CompositeViewer support

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.


JPEGFactory

Note  Also see [40]
Cquote1.png 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[1]
— James Turner
Cquote2.png
Cquote1.png 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) [2]
— James Turner
Cquote2.png
Cquote1.png 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.[3]
— Curtis Olson
Cquote2.png
Cquote1.png I wanted to capture the FG imagery and stream it over the web... (or some similar solution) [4]
Cquote2.png
Cquote1.png 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.[5]
— Curtis Olson
Cquote2.png
Cquote1.png 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.[6]
Cquote2.png
Cquote1.png 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.[7]
Cquote2.png
Cquote1.png 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[8]
Cquote2.png

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) [41] [42] [43] [44] [45], 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.

  1. James Turner (Tue, 11 Jun 2013 22:40:38 -0700). Re: [Flightgear-devel] Enabling JPEG factory causes fgfs/GIT to fail compiling.
  2. James Turner (Tue, 17 Sep 2013 04:17:15 -0700). Re: [Flightgear-devel] --jpg-httpd command line option.
  3. Curtis Olson (Tue, 17 Sep 2013 11:51:00 -0700). Re: [Flightgear-devel] --jpg-httpd command line option.
  4.  (). .
  5. Curtis Olson (Tue, 17 Sep 2013 11:51:00 -0700). Re: [Flightgear-devel] --jpg-httpd command line option.
  6.  (). .
  7.  (). .
  8.  (). .

Finally

...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.