Invocation: establish a concept how to handle parameter data

This was an extended digression into architecture planning,
which became necessary in order to suitably map out the role
for the `TurnoutSystem` — which can now be defined as ''mediator''
to connect and forward control- and parameter data while specific
render invocation proceeds through the render node network.

src/steam/engine/exit-node.hpp

@@ -58,7 +58,7 @@ namespace engine {
    * @warning ExitNode should ideally be NonCopyable, since it is referred by the JobTicket
    *          However, we need to clone-and-remould Segments (Split-Splice-Algo), and this implies
    *          that the render nodes can be shared among multiple Segments. If all these assessments
-   *          are correct an only be decided when the actual memory management is settled.
+   *          are correct can only be decided when the actual memory management is settled.
    */
   class ExitNode
     : util::Cloneable

src/steam/engine/render-invocation.cpp

@@ -15,19 +15,22 @@
 /** @file render-invocation.cpp
  ** Implementation details regarding the invocation of a single render node
  ** @deprecated very likely to happen in a different way, while the concept remains valid
- ** @todo unfinished draft from 2009 regarding the render process
+ ** @todo WIP-WIP-WIP 12/2024 about to build a Render Node invocation, combining the old
+ **                   unfinished draft from 2009 with the new Render Engine code
  */
 
 
-#include "steam/engine/render-invocation.hpp"
 #include "steam/engine/turnout-system.hpp"
+#include "steam/engine/render-invocation.hpp"
+
+
+using vault::gear::JobParameter;
 
 
 namespace steam {
 namespace engine {
   
   namespace { // Details...
-
     
   } // (END) Details...
   
@@ -36,20 +39,36 @@ namespace engine {
 //  using mobject::session::Effect;
   
   
+  string
+  RenderInvocation::diagnostic()  const
+  {
+    return "TODO ... what can the ExitNode tell us here?";    ///////////////////////////////////////////////TICKET #1367 : once we have a working draft of a node invocation, it should be possible to retrieve some Node-Spec here...
+  }
+  
+  InvocationInstanceID
+  RenderInvocation::buildInstanceID (HashVal)  const
+  {
+    return InvocationInstanceID();                     //////////////////////////////////////////////////////TICKET #1278 : so what do we need here for real, finally?
+  }
+  
+  size_t
+  RenderInvocation::hashOfInstance (InvocationInstanceID invoKey)  const
+  {                                                          ////////////////////////////////////////////////TICKET #1295 : settle upon the parameters actually needed and decide what goes into this hash
+    std::hash<size_t> hashr;
+    HashVal res = hashr (invoKey.frameNumber);
+    return res;
+  }
+  
+  
   /** @note this builds a one-way off invocation state context
    *        and then forwards the call; this may or may not cause
    *        actual calculations, depending on the cache.
-   *  @todo for real use within the engine, the pull()-call should be
-   *        dispatched through the scheduler; of course then the call semantics
-   *        would be completely different. Maybe this invocation will be test only?  
    */
-  BuffHandle
-  RenderInvocation::operator[] (size_t channel)
-  {
-    REQUIRE (theNode_);
-    REQUIRE (channel < size());
+  void
+  RenderInvocation::invokeJobOperation (JobParameter invoParam)
+  {                                                          ////////////////////////////////////////////////TICKET #905 : yess.... finally DO IT
+    UNIMPLEMENTED ("how to »doIt«");
     
-    StateProxy invocationState;
 #if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #1367 : Rebuild the Node Invocation
     return theNode_->pull(invocationState, channel);
 #endif    /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #1367 : Rebuild the Node Invocation

src/steam/engine/render-invocation.hpp

@@ -15,11 +15,12 @@
  ** Initiate a single calculation unit within the renderengine.
  ** Usually, this will cause the rendering of a single frame or sub-frame.
  ** 
- ** @todo unfinished draft from 2009 regarding the render process
+ ** @todo WIP-WIP-WIP 2024-12 finally about to connect the unfinished draft from 2009
+ **       with the engine structures built bottom-up meanwhile    ///////////////////////////////////////////TICKET #905 : Work out what parameters are required to invoke the real code available now....
  ** 
  ** @see engine::ProcNode
- ** @see StateClosure
- ** @see node-basic-test.cpp
+ ** @see turnout-system.hpp
+ ** @see NodeBasic_test
  **
  */
 
@@ -27,11 +28,9 @@
 #define ENGINE_RENDER_INVOCATION_H
 
 
-//#include "steam/engine/state-closure.hpp"
-//#include "steam/engine/proc-node.hpp"    ///////////////////////////////TODO clarify if required further on
-#include "steam/engine/connectivity-obsolete.hpp"
-#include "steam/engine/buffhandle.hpp"
-//#include "steam/engine/bufftable-obsolete.hpp"
+#include "vault/gear/job.h"
+#include "steam/engine/proc-node.hpp"
+//#include "steam/engine/buffhandle.hpp"
 
 
 
@@ -41,32 +40,37 @@ namespace engine {
   
   
   /**
+   * A concrete JobFunctor with the ability to activate the »Render Node Network«.
    * @todo write type comment
+   * @warning WIP-WIP 2024-12 rework render node invocation for »Playback Vertical Slice«
    */
   class RenderInvocation
+    : public vault::gear::JobClosure                         ////////////////////////////////////////////////TICKET #1287 : should inherit from JobFunctor, get rid of the C-isms
     {
-      ProcNode* theNode_;
+      ProcNode& theNode_;
       
-    public:
-      RenderInvocation (ProcNode* exitNode)
-        : theNode_(exitNode)
+      
+      /* === JobFunctor Interface === */
+      
+      JobKind
+      getJobKind()  const override
         {
-          REQUIRE (theNode_);
+          return CALC_JOB;
         }
       
-      size_t size() { return theNode_->nrO(); }
-      
-      /** pull calculated data from the N-th node output channel */
-      BuffHandle operator[] (size_t channel);
+      string diagnostic()  const override;
       
+      InvocationInstanceID buildInstanceID (HashVal)  const override;      //////////////////////////////////TICKET #1278 : so what do we need here for real, finally?
+      size_t hashOfInstance (InvocationInstanceID invoKey)  const override;
       
+      void invokeJobOperation (vault::gear::JobParameter);
       
+    public:
+      RenderInvocation (ProcNode& exitNode)
+        : theNode_(exitNode)
+        { }
     };
   
-  ///////////////////////////////////TODO: currently just fleshing out the API
-  
-  
-  
   
   
 }} // namespace steam::engine

src/steam/engine/turnout-system.cpp

@@ -35,51 +35,6 @@ namespace engine {
   
   
   /** @internal */
-  BuffHandle
-  StateProxy::allocateBuffer (const lumiera::StreamType*)
-  {
-    UNIMPLEMENTED ("allocate a suitable buffer to hold a frame of the denoted type");
-  }
-  
-  
-      
-  void
-  StateProxy::releaseBuffer (BuffHandle& bh)
-  {
-    UNIMPLEMENTED ("free a buffer");
-  }
-  
-  
-      
-  BuffHandle
-  StateProxy::fetch (FrameID const& fID)
-  {
-    UNIMPLEMENTED ("fetch a buffer with input data");
-  }
-  
-  
-      
-  void
-  StateProxy::is_calculated (BuffHandle const& bh)
-  {
-    UNIMPLEMENTED ("declare a buffer as fully calculated and done");
-  }
-  
-  
-      
-  FrameID const&
-  StateProxy::genFrameID (NodeID const&, uint chanNo)
-  {
-    UNIMPLEMENTED ("derive/generate an ID to denote this specific fame+Node position in the graph");
-  }
-  
-  
-
-  BuffTableStorage&
-  StateProxy::getBuffTableStorage() /////////////TODO need somehow to denote the specific storage requirements
-  {
-    UNIMPLEMENTED ("allocate a chunk of storage suitable for holding the buffer pointer tables");
-  }
   
   
 }} // namespace engine

src/steam/engine/turnout-system.hpp

@@ -13,14 +13,22 @@
 
 
 /** @file turnout-system.hpp
- ** Access point to the state of a frame rendering evaluation.
- ** The rendering of frames is triggered from a render job, and recursively
- ** retrieves the data from predecessor nodes. Some statefull aspects are involved
- ** into this recursive evaluation, beyond the data in the local call stack. Such
- ** additional statefull dependencies are problematic (regarding concurrency and
- ** throughput) and are thus abstracted from the actual processing operations
- ** with the help of the steam::engine::StateClosure interface
- ** @todo unfinished draft from 2009 regarding the render process
+ ** THe actual state of a frame rendering evaluation parametrised for a single job.
+ ** The rendering of frames is triggered from a render job, and recursively retrieves the data
+ ** from predecessor render nodes, prepared, configured and interconnected by the Builder.
+ ** Some statefull aspects can be involved into this recursive evaluation, beyond the data
+ ** passed directly through the recursive calls and interconnected data buffers. Notably,
+ ** some operations need direct call parameters, e.g. the frame number to retrieve or
+ ** the actual parametrisation of an effect, which draws from _parameter automation._
+ ** Moreover, when rendering interactively, parts of the render pipeline may be
+ ** changed dynamically by mute toggles or selecting an output in the viever's
+ ** _Switch Board.
+ ** 
+ ** The TurnoutSystem is related to the actual incidence and is created dynamically,
+ ** while connecting to all the existing \ref Turnout elements sitting in the render node ports.
+ ** It acts as mediator and data exchange hub, while gearing up the actual invocation to cause
+ ** calculation of media data in the render nodes connected below
+ ** @todo WIP-WIP-WIP 12/2024 now combining the draft from 2009 / 2012 with recent engine development
  */
 
 
@@ -28,8 +36,7 @@
 #define STEAM_ENGINE_TURNOUT_SYSTEM_H
 
 
-//#include "steam/engine/proc-node.hpp"  /////////////////////OOO dependency cycle ProcNode <-> TurnoutSystem
-#include "steam/engine/state-closure.hpp"
+#include "steam/engine/state-closure.hpp" /////////////////////OOO will take on a different role (if any)
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////TICKET #1367 : Rebuild the Node Invocation
 
 
@@ -38,30 +45,12 @@ namespace engine {
 
 
 
-/////////////////////////////////////////////////////////////////////////////////////////////////////////////TICKET #1367 : Rebuild the Node Invocation
-  class StateProxy
-    : public StateClosure
-    {
-      
-    private: /* === top-level implementation of the StateClosure interface === */
-      
-      BuffHandle allocateBuffer (const lumiera::StreamType*);              //////////////////////////TICKET #828
-      
-      void releaseBuffer (BuffHandle& bh);
-      
-      BuffHandle fetch (FrameID const& fID);
-      
-      void is_calculated (BuffHandle const& bh);
-      
-      FrameID const& genFrameID (NodeID const&, uint chanNo);
-
-      BuffTableStorage& getBuffTableStorage();
-      
-      virtual StateClosure& getCurrentImplementation () { return *this; }
-      
-    };
-/////////////////////////////////////////////////////////////////////////////////////////////////////////////TICKET #1367 : Rebuild the Node Invocation
-    
+  /**
+   * Communication hub to coordinate and activate the »Render Node Network« performance.
+   * An instance will be created on the stack for each evaluation of a [render job](\ref RenderInvocation).
+   * It provides access to common invocation parameters, an extension system to register further _data slots,_
+   * and initiates the recursive pull()-call into the render node network as attached for this call.
+   */
   class TurnoutSystem
     /////////////////////////////////////////OOO von wo erbt das?? laut ursprünglichem Konzept von StateClosure ... bin mir aber nicht mehr sicher
     {

src/steam/engine/weaving-pattern-builder.hpp

@@ -350,6 +350,20 @@ namespace engine {
   using SimpleDirectInvoke = SimpleWeavingPattern<DirectFunctionInvocation<N,FUN>>;
   
   
+  /**
+   * A low-level Builder to prepare and adapt for a specific node invocation.
+   * In this context, »weaving« refers to the way parameters and results of an
+   * processing function are provided, combined and forwarded within the setup
+   * for an actual Render Node invocation. When the invocation happens, a kind
+   * of preconfigured _blue print_ or invocation plan is executed; the purpose
+   * of the build at »Level-2« (≙the purpose of this code) is to preconfigure
+   * this invocation scheme. Using a _low level builder_ as controlled by the
+   * actual NodeBuilder and PortBuilder allows to introduce extension points
+   * and helps to abstract away internal technical details of the invocation.
+   * @tparam POL allocation and context configuration policy
+   * @tparam N   maximum number of input and output slots
+   * @tparam FUN function or invocation adapter to invoke
+   */
   template<class POL, uint N, class FUN>
   struct WeavingBuilder
     : util::MoveOnly

tests/46node.tests

@@ -6,6 +6,10 @@ PLANNED "Proc Node basics" NodeBasic_test <<END
 END
 
 
+PLANNED "Proc Node creation" NodeBuilder_test <<END
+END
+
+
 TEST "Proc Node test support" NodeDevel_test <<END
 END
 

tests/core/steam/engine/node-basic-test.cpp

@@ -47,7 +47,7 @@ namespace test  {
      * happening in correct order.
      */
     class TestContext
-      : public StateProxy
+//      : public StateProxy
       {
         
         //////////////TODO: facility to verify the right access operations get called
@@ -73,12 +73,12 @@ namespace test  {
           UNIMPLEMENTED ("build a simple render node and then activate it");
           
           AllocationCluster alloc;
+#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #1367 : Rebuild the Node Invocation
           NodeFactory nodeFab(alloc);
           
           ProcNode * testSource;  ///////////TODO: how to fabricate a test Source-Node????
           
           
-#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #1367 : Rebuild the Node Invocation
           WiringSituation setup(testSource);
           
           PEffect pEffect = createTestEffectMObject();

tests/core/steam/engine/node-builder-test.cpp

@@ -0,0 +1,52 @@
+/*
+  NodeBuilder(Test)  -  creation and setup of render nodes
+
+   Copyright (C)
+     2024,            Hermann Vosseler <Ichthyostega@web.de>
+
+  **Lumiera** is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by the
+  Free Software Foundation; either version 2 of the License, or (at your
+  option) any later version. See the file COPYING for further details.
+
+* *****************************************************************/
+
+/** @file node-builder-test.cpp
+ ** unit test \ref NodeBuilder_test
+ */
+
+
+#include "lib/test/run.hpp"
+#include "steam/engine/node-builder.hpp"
+//#include "lib/util.hpp"
+
+
+using std::string;
+
+
+namespace steam {
+namespace engine{
+namespace test  {
+  
+  
+  
+  
+  /***************************************************************//**
+   * @test creating and configuring various kinds of render nodes.
+   */
+  class NodeBuilder_test : public Test
+    {
+      virtual void
+      run (Arg)
+        {
+          UNIMPLEMENTED ("build and wire some render nodes");
+        } 
+    };
+  
+  
+  /** Register this test class... */
+  LAUNCHER (NodeBuilder_test, "unit node");
+  
+  
+  
+}}} // namespace steam::engine::test

tests/core/steam/engine/node-devel-test.cpp

@@ -268,9 +268,12 @@ namespace test  {
         }
       
       
+      
       /** @test demonstrate simple usage of test-render setup
        *   - access the TestRandOntology as singleton
        *   - create a Spec record
+       *   - retrieve a functor bound suitably to invoke
+       *     data processing code from the TestRandOntology
        */
       void
       testRand_simpleUsage()

tests/core/steam/engine/node-factory-test.cpp

@@ -13,6 +13,9 @@
 
 /** @file node-factory-test.cpp
  ** unit test \ref NodeFactory_test
+ ** @todo 12/2024 this test will focus on the high-level integration,
+ **       which is future work and possibly addressed in the next »Vertical Slice«
+ **       when we add processing of a given media clip from disk.
  */
 
 
@@ -35,10 +38,11 @@ namespace test  {
    */
   class NodeFactory_test : public Test
     {
-      virtual void run(Arg) 
+      virtual void
+      run (Arg)
         {
           UNIMPLEMENTED ("build and wire some render nodes");
-        } 
+        }
     };