Under the hood of Canvas

Canvas - the FlightGear 2D drawing API
Canvas - Main Page Canvas News - for the latest developments Shiva Alternatives - ongoing work for Core Profile support Canvas Efforts - projects using the Canvas system Canvas FAQs - frequently asked questions Canvas - Getting started Canvas Development (core) Canvas Troubleshooting (core) Canvas Sandbox (core) PUI2Canvas (PUI/XML Parser) Canvas GUI Canvas Widgets Canvas Maps Canvas Snippets
RFC
Canvas Instancing Howto:New Canvas Execution Model Canvas SVG Canvas Popout Windows Canvas Scenery Overlays
Frameworks
Canvas Map API (soon deprecated!) Canvas MapStructure Canvas MapStructure Layers MapStructure Snippets Canvas Radar Canvas Animation Framework (WIP) Canvas Plotting Framework (WIP) Canvas MFD Framework Canvas ND Framework Canvas PFD Framework Canvas MCDU Framework Canvas EFB Framework Canvas Wrappers Canvas Glass Cockpit Efforts
Tutorials
Howto:Getting started with Canvas Howto: Canvas Troubleshooting Howto:Adding a canvas to a GUI dialog (PUI!) Howto:Creating a Canvas GUI dialog file (New) Howto:Dynamic Liveries via Canvas (new) Howto:Creating a Canvas GUI Widget Howto:Add a 2D canvas instrument to your aircraft Howto:Parsing 2D Instruments using the Canvas Howto:Creating fullscreen Canvas applications Howto:Use SVG inside a Canvas Howto:Extend the Canvas SVG module Howto:Serializing a Canvas to SVG Howto:Canvas applications as Nasal submodules Howto:Using raster images and nested canvases Canvas HUD Howto:Project 3D to 2D coordinates on desktop canvas
Reference
Canvas Element Group Image Map Path Text Canvas Nasal API MessageBox Layout System Canvas GUI API Canvas draw library Event Handling
Related
Canvas Properties Unifying the 2D rendering backend via canvas Howto:Use a Camera View in an Instrument Howto:Extending Canvas to support rendering 3D models Howto:Extending Canvas to support MathGL
To be ported
Navigation display Map FGCanvas Canvas Nasal/JavaScript Subset
Deprecated by Canvas
Complex Glass Cockpit Avionics
(click on headings to toggle)

This article is a stub. You can help the wiki by expanding it.

abstraction layers always come with a penalty. That applies particularly when we're using them for use-cases other than what they're designed for (e.g. doing 3D stuff in 2D without any explicit support for that)

• Nasal
• Property Tree
• Canvas
• SGSubsystemMgr
• OpenSceneGraph/ShivaVG
• and finally, OpenGL

So, we need to keep in mind what is happening behind the scenes between the various abstraction layers, i.e. the translation overhead caused by going from one abstraction to the next one below it. The first step is Nasal (FlightGear's scripting language), it is used to provide an OSG-like high-level abstraction, but all it really does (well usually) is setting doens of properties in the global property tree under /canvas for you behind the scenes. Then, there is the property tree, it has listeners that are mappped to the Canvas subsystem which looks for a few well-defined properties and checks whether the changed properties match the heuristics to make sense (name of the property, type and value written to it, current state/mode of the element etc) - whenever that is the case, the whole Canvas must be marked as "dirty", triggering everything to be rendered. And then there is the "element" level: Each Canvas just represents a FBO/RTT context (an off-screen texture that is rendered but not normally visible), but there isn't anything to be rendered yet - it's just an empty texture with a background color, a size and a few other attributes. To become something that can be rendered, the top-level element that must be always added to a canvas is a so called "group", which represents a group of items that can be rendered, including other groups (and so on). Internally, what takes place here is that we have a base class implementing a Canvas::Element, this exposes attributes and methods that all Canvas elements have in common, including groups -because they're just that: elements inheriting from Canvas::Element. That is why all elements must be registered at the group level, e.g. images, paths or text nodes are registered by letting the Group element watch for property accesses that create new child-nodes using a corresponding name (e.g. image, path or text). The name serves as the lookup key for the lookup to get the helpers out of the factories implementing each element. Under the hood, this makes sure that the corresponding element receives "events" (property write notifications using listeners) whenever one of its child nodes is updated - but at that point, it doesn't yet know whether the event is really valid or relevant, because it still hasn't parsed the property name, the type or the value that was written to it - and checked whether those changes actually make sense in the element's given scope. Still, the property/canvas subsystem will make sure to dispatch events by invoking the element's notification handler so that it can parse/process the corresponding updates properly. That is one of the reasons why unnecessary property updates will usually affect performance of rendering the whole Canvas, because its top-level <group> element basically serves as a list of render-able elements (text, paths, images), and whenever one of those changes, the corresponding scene graph node is marked as dirty, and must be updated, and the whole Canvas must be updated/re-rendered afterwards. Thus, when dealing with primitives that may need to be separately hidden/shown, updated, animated, transformed etc - it makes sense to "group" them accordingly, i.e. by adding them to a separate group that can be directly addressed. This is also where the abstraction overhead comes in, because whenever we are dealing with such lists of render-able elements, there is not just the property tree representation in the global property tree, but also an internal representation that maps the whole property tree representation to something that makes sense to OpenSceneGraph, and in turn, to OpenGL. If we don't ever have to update a complex Canvas scenegraph after creating it, all it will do is render a textured quad - which it can do really fast, but once we introduce many state changes, we make things unnecessarily difficult and heavy, even if the state changes are redundant, because identical values are written to the corresponding nodes. Obviously, Canvas being all about modern avionics and dynamic stuff, we cannot just reuse previously lines/shapes - but what we can do is pre-allocate the corresponding data structures and clear/reuse those selectively, to reduce the allocation/re-allocation overhead. The next challenge is carefully reviewing dynamic elements of the scene, and grouping those accordingly (e.g. background images vs. elements that need to be animated)- i.e. looking at the requirements of what needs to be updated, and how that will affect the scene. For example, a group that merely needs to be transformed/translated will have much less of an impact than one that always needs to be updated/redrawn entirely. However, sometimes there are elements that merely need translations, but which still need different elements, e.g. labels - at that point, it makes sense to introduce a new, separate, group to keep the labels.

References

References