Add example for RenderableSphereSpout (#3208)

* Example asset for RenderableSphereSpout

* fixed path to example texture

* removed unnecessary variables

* Update example and improve the documentation handling for the spout classes

* Apply new naming scheme

* added PR review changes

* changed to correct submodules

* submodules updated to correct version

* reverted wrong submodule updates

---------

Co-authored-by: Arohdin <adam.rohdin@liu.se>
Co-authored-by: Alexander Bock <alexander.bock@liu.se>

data/assets/examples/renderable/renderablespherespout/spherespout.asset

@@ -0,0 +1,30 @@
+-- Basic
+-- This example renders a sphere with a texture that is provided by another application
+-- on the same computer using the SPOUT library. Note that this library is only available
+-- on Windows. A SPOUT-enabled application can share a texture using a user-defined
+-- name, which is used as the `SpoutName` here to receive that image. This allows the
+-- integration of any generated image.
+
+local Node = {
+  Identifier = "RenderableSphereSpout_Example",
+  Renderable = {
+    Type = "RenderableSphereSpout",
+    Size = 333,
+    Segments = 32,
+    -- The name under which the other application is sharing an image
+    SpoutName = "WV_SPOUT"
+  },
+  GUI = {
+    Name = "Basic",
+    Path = "/Examples/RenderableSphereSpout"
+  }
+}
+
+asset.onInitialize(function()
+  openspace.addSceneGraphNode(Node)
+end)
+
+
+asset.onDeinitialize(function()
+  openspace.removeSceneGraphNode(Node)
+end)

modules/spout/renderablespherespout.cpp

@@ -31,40 +31,32 @@
 #include <openspace/util/sphere.h>
 #include <ghoul/opengl/texture.h>
 
+// The RenderableSphereSpout can be used to render a sphere with a texture that is
+// provided by another application on the same computer using the SPOUT library. Note that
+// this library is only available on Windows.
+
+namespace {
+    struct [[codegen::Dictionary(RenderableSphereSpout)]] Parameters {
+        // Specifies the GUI name of the RenderableSphereSpout
+        std::optional<std::string> name;
+    };
+#include "renderablespherespout_codegen.cpp"
+} // namespace
+
 namespace openspace {
 
 documentation::Documentation RenderableSphereSpout::Documentation() {
-    using namespace openspace::documentation;
-    return {
-        "Renderable Sphere Spout",
-        "spout_sphere_spout",
-        "",
-        {
-            {
-                "Name",
-                new StringVerifier,
-                Optional::Yes,
-                "Specifies the GUI name of the RenderableSphereSpout"
-            },
-            {
-                spout::SpoutReceiverPropertyProxy::NameInfoProperty().identifier,
-                new StringVerifier,
-                Optional::Yes,
-                spout::SpoutReceiverPropertyProxy::NameInfoProperty().description
-            }
-        }
-    };
+    return codegen::doc<Parameters>(
+        "spout_renderablespherespout",
+        spout::SpoutReceiverPropertyProxy::Documentation()
+    );
 }
 
 RenderableSphereSpout::RenderableSphereSpout(const ghoul::Dictionary& dictionary)
     : RenderableSphere(dictionary)
     , _spoutReceiver(*this, dictionary)
 {
-    documentation::testSpecificationAndThrow(
-        Documentation(),
-        dictionary,
-        "RenderableSphereSpout"
-    );
+    codegen::bake<Parameters>(dictionary);
 
     int iIdentifier = 0;
     if (_identifier.empty()) {

modules/spout/spoutwrapper.cpp

@@ -45,7 +45,7 @@ namespace {
         "SpoutName",
         "Spout Receiver Name",
         "This value explicitly sets the Spout receiver to use a specific name. If this "
-        "is not a valid name, an empty image is used.",
+        "is not a valid name, the first Spout image is used instead",
         openspace::properties::Property::Visibility::AdvancedUser
     };
 
@@ -64,6 +64,18 @@ namespace {
         "If this property is trigged, the 'SpoutSelection' options will be refreshed.",
         openspace::properties::Property::Visibility::AdvancedUser
     };
+
+    struct [[codegen::Dictionary(SpoutReceiver)]] ReceiverParameters {
+        // [[codegen::verbatim(NameReceiverInfo.description)]]
+        std::optional<std::string> spoutName;
+    };
+
+    struct [[codegen::Dictionary(SpoutSender)]] SenderParameters {
+        // [[codegen::verbatim(NameSenderInfo.description)]]
+        std::string spoutName;
+    };
+
+#include "spoutwrapper_codegen.cpp"
 } // namespace
 
 namespace openspace::spout {
@@ -127,7 +139,7 @@ SpoutReceiver::SpoutReceiver() {}
 
 SpoutReceiver::~SpoutReceiver() {}
 
-const std::vector<std::string> &SpoutReceiver::spoutReceiverList() {
+const std::vector<std::string>& SpoutReceiver::spoutReceiverList() {
     if (!_spoutHandle) {
         return _receiverList;
     }
@@ -338,18 +350,20 @@ const properties::Property::PropertyInfo& SpoutReceiverPropertyProxy::UpdateInfo
     return UpdateInfo;
 }
 
+documentation::Documentation SpoutReceiverPropertyProxy::Documentation() {
+    return codegen::doc<ReceiverParameters>("spout_receiver");
+}
+
 SpoutReceiverPropertyProxy::SpoutReceiverPropertyProxy(properties::PropertyOwner& owner,
                                                       const ghoul::Dictionary& dictionary)
     : _spoutName(NameReceiverInfo)
     , _spoutSelection(SelectionInfo)
     , _updateSelection(UpdateInfo)
 {
-    if (dictionary.hasKey(NameReceiverInfo.identifier)) {
-        _spoutName = dictionary.value<std::string>(NameReceiverInfo.identifier);
-    }
-    else {
-        _isSelectAny = true;
-    }
+    const ReceiverParameters p = codegen::bake<ReceiverParameters>(dictionary);
+
+    _spoutName = p.spoutName.value_or(_spoutName);
+    _isSelectAny = !p.spoutName.has_value();
 
     _spoutName.onChange([this]() { _isSpoutDirty = true; });
     owner.addProperty(_spoutName);
@@ -407,7 +421,6 @@ void SpoutReceiverPropertyProxy::releaseReceiver() {
     SpoutReceiver::releaseReceiver();
 }
 
-
 SpoutSender::SpoutSender() {}
 
 SpoutSender::~SpoutSender() {}
@@ -580,17 +593,17 @@ const properties::Property::PropertyInfo& SpoutSenderPropertyProxy::NameInfoProp
     return NameSenderInfo;
 }
 
+documentation::Documentation SpoutSenderPropertyProxy::Documentation() {
+    return codegen::doc<SenderParameters>("spout_sender");
+}
+
 SpoutSenderPropertyProxy::SpoutSenderPropertyProxy(properties::PropertyOwner& owner,
                                                    const ghoul::Dictionary& dictionary)
     : _spoutName(NameSenderInfo)
 {
-    if (dictionary.hasKey(NameSenderInfo.identifier)) {
-        _spoutName = dictionary.value<std::string>(NameSenderInfo.identifier);
-    }
-    else {
-        LWARNING(std::format("Sender does not have a name"));
-    }
+    const SenderParameters p = codegen::bake<SenderParameters>(dictionary);
 
+    _spoutName = p.spoutName;
     _spoutName.onChange([this]() { _isSpoutDirty = true; });
     owner.addProperty(_spoutName);
 }

modules/spout/spoutwrapper.h

@@ -25,6 +25,7 @@
 #ifndef __OPENSPACE_MODULE_SPOUT___SPOUTWRAPPER___H__
 #define __OPENSPACE_MODULE_SPOUT___SPOUTWRAPPER___H__
 
+#include <openspace/documentation/documentation.h>
 #include <openspace/properties/optionproperty.h>
 #include <openspace/properties/propertyowner.h>
 #include <openspace/properties/stringproperty.h>
@@ -123,6 +124,8 @@ public:
     bool updateReceiver() override;
     void releaseReceiver() override;
 
+    static documentation::Documentation Documentation();
+
 private:
     properties::StringProperty _spoutName;
     properties::OptionProperty _spoutSelection;
@@ -179,6 +182,8 @@ public:
     bool updateSender(unsigned int texture, unsigned int textureType) override;
     void releaseSender() override;
 
+    static documentation::Documentation Documentation();
+
 private:
     properties::StringProperty _spoutName;