Template talk:Custom Canvas Element

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-CPDF
• Navigate to $SG_SRC/canvas/elements
• Create a new set of files CPDF.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:

Caution  This custom Canvas element requires a 3rd party library which is not currently used by SimGear/FlightGear, so that the top-level CMakeLists.txt file in $SG_SRC needs to be modified to add a corresponding findPackage() call and you also need to download/install the corresponding library for building sg/fg. In addition, the CMake module itself may need to be placed in $SG_SRC/CMakeModules: CPDF: (required cmake changes) We need to edit the top-level cmake file to check for our new dependency: Poppler diff --git a/CMakeLists.txt b/CMakeLists.txt index 5e3b905..711547b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -204,6 +204,7 @@ else() endif(ENABLE_SOUND) find_package(OpenSceneGraph 3.2.0 REQUIRED osgText osgSim osgDB osgParticle osgGA osgViewer osgUtil) + # put FindPoppler.cmake from https://github.com/Eyescale/CMake/blob/master/FindPoppler.cmake into $SG_SRC/CMakeModules + find_package(Poppler) endif(SIMGEAR_HEADLESS) find_package(ZLIB REQUIRED)

CPDF: Canvas PDF (required cmake changes)

Step #1 is editing $SG_SRC/canvas/elements/CMakeLists.txt to add our set of new files

diff --git a/simgear/canvas/elements/CMakeLists.txt b/simgear/canvas/elements/CMakeLists.txt
index 2b537c0..08f9857 100644
--- a/simgear/canvas/elements/CMakeLists.txt
+++ b/simgear/canvas/elements/CMakeLists.txt
@@ -7,6 +7,7 @@ set(HEADERS
   CanvasMap.hxx
   CanvasPath.hxx
   CanvasText.hxx
+  CanvasCPDF.hxx
 )
 
 set(DETAIL_HEADERS
@@ -20,6 +21,7 @@ set(SOURCES
   CanvasMap.cxx
   CanvasPath.cxx
   CanvasText.cxx
+  CanvasCPDF.cxx
 )
 
 simgear_scene_component(canvas-elements canvas/elements "${SOURCES}" "${HEADERS}")
@@ -28,4 +30,4 @@ simgear_component(canvas-elements/detail canvas/elements/detail "" "${DETAIL_HEA
 add_boost_test(canvas_element
   SOURCES canvas_element_test.cpp
   LIBRARIES ${TEST_LIBS}
-)
\ No newline at end of file
+)

CPDF: Canvas PDF (minimal C++ changes)

Step #2 is creating the new files for our C++ code

diff --git a/simgear/canvas/elements/CanvasCPDF.cxx b/simgear/canvas/elements/CanvasCPDF.cxx
new file mode 100644
index 0000000..8004245
--- /dev/null
+++ b/simgear/canvas/elements/CanvasCPDF.cxx
@@ -0,0 +1,87 @@
+// CPDF.cxx: Stub for exposing OSG PDF support as a dedicated Canvas element
+//
+// Copyright (C) 2015  your name
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Library General Public
+// License as published by the Free Software Foundation; either
+// version 2 of the License, or (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Library General Public License for more details.
+//
+// You should have received a copy of the GNU Library General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
+
+#include "CanvasCPDF.hxx"
+
+
+namespace simgear
+{
+namespace canvas
+{
+  const std::string CPDF::TYPE_NAME = "cpdf";
+  //----------------------------------------------------------------------------
+  void CPDF::staticInit()
+  {
+    Image::staticInit();
+
+    if( isInit<CPDF>() )
+      return;
+
+    // Do some initialization if needed...
+  }
+
+  //----------------------------------------------------------------------------
+  CPDF::CPDF( const CanvasWeakPtr& canvas,
+            const SGPropertyNode_ptr& node,
+            const Style& parent_style,
+            ElementWeakPtr parent ):
+    Image(canvas, node, parent_style, parent)
+  {
+    SG_LOG(SG_GENERAL, SG_ALERT, "New CPDF element added!");
+  }
+
+  //----------------------------------------------------------------------------
+  CPDF::~CPDF()
+  {
+    SG_LOG(SG_GENERAL, SG_ALERT, "New CPDF element removed!");
+  }
+
+  //----------------------------------------------------------------------------
+  void CPDF::update(double dt)
+  {
+    Image::update(dt);
+  }
+
+  //----------------------------------------------------------------------------
+  void CPDF::childAdded(SGPropertyNode* parent, SGPropertyNode* child)
+  {
+      return Image::childAdded(parent, child);
+  }
+
+  //----------------------------------------------------------------------------
+  void CPDF::childRemoved(SGPropertyNode* parent, SGPropertyNode* child)
+  {
+      return Image::childRemoved(parent, child);
+  }
+
+  //----------------------------------------------------------------------------
+  void CPDF::valueChanged(SGPropertyNode* child)
+  {
+    return Image::valueChanged(child);
+  }
+
+  //----------------------------------------------------------------------------
+  void CPDF::childChanged(SGPropertyNode* child)
+  {
+  }
+
+  //----------------------------------------------------------------------------
+
+} // namespace canvas
+} // namespace simgear
+
diff --git a/simgear/canvas/elements/CanvasCPDF.hxx b/simgear/canvas/elements/CanvasCPDF.hxx
new file mode 100644
index 0000000..1cd4062
--- /dev/null
+++ b/simgear/canvas/elements/CanvasCPDF.hxx
@@ -0,0 +1,61 @@
+// CanvasCPDF.hxx: Stub for exposing OSG PDF support as a dedicated Canvas element
+//
+//
+// Copyright (C) 2015  your name
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Library General Public
+// License as published by the Free Software Foundation; either
+// version 2 of the License, or (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Library General Public License for more details.
+//
+// You should have received a copy of the GNU Library General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
+
+#ifndef CANVAS_CPDF_HXX_
+#define CANVAS_CPDF_HXX_
+
+#include "CanvasImage.hxx"
+
+#include <boost/shared_ptr.hpp>
+
+namespace simgear
+{
+namespace canvas
+{
+  class CPDF:
+    public Image
+  {
+    public:
+      static const std::string TYPE_NAME;
+      static void staticInit();
+
+      CPDF( const CanvasWeakPtr& canvas,
+           const SGPropertyNode_ptr& node,
+           const Style& parent_style,
+           ElementWeakPtr parent = 0 );
+      virtual ~CPDF();
+
+      virtual void update(double dt);
+
+      virtual void childAdded( SGPropertyNode * parent,
+                               SGPropertyNode * child );
+      virtual void childRemoved( SGPropertyNode * parent,
+                                 SGPropertyNode * child );
+      virtual void valueChanged(SGPropertyNode * child);
+
+    protected:
+
+      virtual void childChanged(SGPropertyNode * child);
+
+  };
+
+} // namespace canvas
+} // namespace simgear
+
+#endif /* CANVAS_CPDF_HXX_ */

CPDF: Canvas PDF (registering the new element)

Step #3 is modifying CanvasGroup.cxx to register our new element

diff --git a/simgear/canvas/elements/CanvasGroup.cxx b/simgear/canvas/elements/CanvasGroup.cxx
index de289a8..49fa2c1 100644
--- a/simgear/canvas/elements/CanvasGroup.cxx
+++ b/simgear/canvas/elements/CanvasGroup.cxx
@@ -21,6 +21,8 @@
 #include "CanvasMap.hxx"
 #include "CanvasPath.hxx"
 #include "CanvasText.hxx"
+#include "CanvasCPDF.hxx"
+
 #include <simgear/canvas/CanvasEventVisitor.hxx>
 #include <simgear/canvas/events/MouseEvent.hxx>
 
@@ -64,6 +66,8 @@ namespace canvas
     add<Map  >(_child_factories);
     add<Path >(_child_factories);
     add<Text >(_child_factories);
+    // add CPDF
+    add<CPDF>(_child_factories);
   }
 
   //----------------------------------------------------------------------------

CPDF: Canvas PDF $FG_ROOT/Nasal/canvas/api.nas changes

Step #4 is extending api.nas to provide Nasal wrappers for the new element (note, the corresponding fgdata structure has been updated recently)

diff --git a/Nasal/canvas/api.nas b/Nasal/canvas/api.nas
index 6d39d03..f98fdd9 100644
--- a/Nasal/canvas/api.nas
+++ b/Nasal/canvas/api.nas
@@ -1099,13 +1099,21 @@ var Image = {
   }
 };
 
+var CPDF = {
+  new: func(ghost)
+  {
+    return {parents: [CPDF, Element.new(ghost)]};
+  },
+};
+ 
 # Element factories used by #Group elements to create children
 Group._element_factories = {
   "group": Group.new,
   "map": Map.new,
   "text": Text.new,
   "path": Path.new,
-  "image": Image.new
+  "image": Image.new,
+  "cpdf": CPDF.new,
 };

CPDF: Canvas PDF (testing the new element using the Nasal Console)

Step #5

var (width,height) = (320,320);
var title = 'Canvas Element test: CPDF';

# create a new window, dimensions are WIDTH x HEIGHT, using the dialog decoration (i.e. titlebar)
var window = canvas.Window.new([width,height],"dialog").set('title',title);

# adding a canvas to the new window and setting up background colors/transparency
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));

# creating the top-level/root group which will contain all other elements/group
var root = myCanvas.createGroup();

var child = root.createChild("cpdf");
# your code goes here