Template:Custom Canvas Element
| Note
This template is used for creating the common boilerplate code required for adding new Canvas elements, such as those frequently discussed on the forum - e.g. support for rendering slaved camera views (tail cam, mirror textures), support for rendering PDF files to a Canvas (e.g. for viewing the manual and/or charts), but also for loading arbitrary 3D models from disk and visualize those using Canvas. In all of these examples, you will typically want to add a new Canvas element, with the main difference being the underlying base class (e.g. anything that involves rendering to a texture would be best handled by sub-classing Canvas::Image instead of Canvas::Element). Most of these ideas have seen quite some discussion over the years, with some being fairly popular among aircraft developers (especially the capability to render scenery views), so that it makes sense to grow a repository of related patches and code snippets to hopefully grow a repository of helpful information and pointers to implement these ideas one day. |
You will want to add a new Canvas::Element subclass whenever you want to add support for features which cannot be currently expressed easily (or efficiently) using existing means/canvas drawing primitives (i.e. via existing elements and scripting space frameworks).
For example, this may involve projects requiring camera support, i.e. rendering scenery views to a texture, rendering 3D models to a texture or doing a complete moving map with terrain elevations/height maps (even though the latter could be implemented by sub-classing Canvas::Image to some degree).
Another good example for implementing new elements is rendering file formats like PDF, 3d models or ESRI shape files.
To create a new element, you need to create a new child class which inherits from Canvas::Element base class (or any of its child-classes, e.g. Canvas::Image) and implement the interface of the parent class by providing/overriding the correspond virtual methods.
To add a new element, these are the main steps:
- Set up a working build environment (including simgear): Building FlightGear
- update/pull simgear,flightgear and fgdata
- check out a new set of topic branches for each repo: git checkout -b topic/canvas-NasalElement
- Navigate to $SG_SRC/canvas/elements
- Create a new set of files NasalElement.cxx/.hxx (as per Adding a new Canvas element)
- add them to $SG_SRC/canvas/elements/CMakeLists.txt (as per Developing using CMake)
- edit $SG_SRC/canvas/elements/CanvasGroup.cxx to register your new element (header and staticInit)
- begin replacing the stubs with your own C++ code
- map the corresponding OSG/library APIs to properties/events understood by the Canvas element (see the valueChanged() and update() methods)
- alternatively, consider using dedicated Nasal/CppBind bindings
Below, you can find patches illustrating how to approach each of these steps using boilerplate code, which you will need to customize/replace accordingly: