turn Dispatcher into an interface

src/proc/engine/dispatch-table.cpp

@@ -0,0 +1,38 @@
+/*
+  DispatchTable  -  implementation of frame job creation
+
+  Copyright (C)         Lumiera.org
+    2012,               Hermann Vosseler <Ichthyostega@web.de>
+
+  This program 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.
+
+  This program 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 General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+* *****************************************************/
+
+
+#include "proc/engine/dispatch-table.hpp"
+//#include "lib/frameid.hpp"
+//#include "proc/state.hpp"
+
+
+
+namespace proc {
+namespace engine {
+  
+  /** */
+  
+  
+  
+  
+}} // namespace engine

src/proc/engine/dispatch-table.hpp

@@ -0,0 +1,63 @@
+/*
+  DISPATCH-TABLE.hpp  -  implementation of frame job creation
+
+  Copyright (C)         Lumiera.org
+    2012,               Hermann Vosseler <Ichthyostega@web.de>
+
+  This program 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.
+
+  This program 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 General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+*/
+
+
+#ifndef PROC_ENGINE_DISPATCH_TABLE_H
+#define PROC_ENGINE_DISPATCH_TABLE_H
+
+#include "proc/common.hpp"
+#include "proc/engine/dispatcher.hpp"
+
+
+
+namespace proc {
+namespace engine {
+  
+  using lib::time::TimeSpan;
+  using lib::time::FSecs;
+  using lib::time::Time;
+//  
+//  class ExitNode;
+  
+  /**
+   * @todo 11/11 extremely fuzzy at the moment
+   */
+  class DispatchTable
+    : public Dispatcher
+    {
+    protected:
+      /** timerange covered by this RenderGraph */
+      TimeSpan segment_;
+      
+    public:
+      DispatchTable()
+        : segment_(Time::ZERO, FSecs(5))
+        {
+          UNIMPLEMENTED ("anything regarding the Engine backbone");
+        }
+      
+    };
+  
+  
+  
+}} // namespace proc::engine
+#endif

src/proc/engine/dispatcher.cpp

@@ -29,6 +29,9 @@
 
 namespace proc {
 namespace engine {
+
+  Dispatcher::~Dispatcher() { }  // emit VTable here....
+  
   
   /** */
   

src/proc/engine/dispatcher.hpp

@@ -28,6 +28,8 @@
 #include "proc/state.hpp"
 #include "lib/time/timevalue.hpp"
 
+#include <boost/noncopyable.hpp>
+
 
 
 namespace proc {
@@ -43,17 +45,13 @@ namespace engine {
    * @todo 11/11 extremely fuzzy at the moment
    */
   class Dispatcher
+    : boost::noncopyable
     {
-    protected:
-      /** timerange covered by this RenderGraph */
-      TimeSpan segment_;
       
     public:
-      Dispatcher()
-        : segment_(Time::ZERO, FSecs(5))
-        {
-          UNIMPLEMENTED ("anything regarding the Engine backbone");
-        }
+      virtual ~Dispatcher();  ///< this is an interface
+      
+      
       
     };
   

src/proc/engine/nodeoperation.hpp

@@ -106,7 +106,7 @@ namespace config {
       bool
       validateBuffers (Invocation& ivo)
         {
-          UNIMPLEMENTED ("Do a final, specifically tailored validation step on the buffers prior to invoking the procees function");
+          UNIMPLEMENTED ("Do a final, specifically tailored validation step on the buffers prior to invoking the process function");
         }
     };
   

src/proc/engine/nodewiring.cpp

@@ -117,8 +117,8 @@ namespace engine {
    *  for the specific wiring situations) use the AllocationCluster
    *  of the current build process, we need to create a new instance
    *  for each newly built segment of the low-level model.
-   *  @note As this ctor creates a WiringFactoryImpl instance, 
-   *        compiling this invocation actually drives the necessary
+   *  @note This ctor creates a WiringFactoryImpl instance, thus 
+   *        compiling this definition actually drives the necessary
    *        template instantiations for all cases encountered while
    *        building the node network.
    */

src/proc/engine/procnode.hpp

@@ -50,6 +50,7 @@
 #include "lib/ref-array.hpp"
 
 #include <vector>
+#include <boost/noncopyable.hpp>
 
 
 
@@ -67,10 +68,17 @@ namespace engine {
   /**
    * Interface: Description of the input and output ports,
    * processing function and predecessor nodes for a given ProcNode.
+   * 
+   * @todo the design of this part is messy in several respects.
+   *       Basically, its left-over from a first prototypical implementation from 2008
+   *       As of 1/2012, we're re-shaping that engine interface and invocation with a top-down approach,
+   *       starting from the player. Anyhow, you can expect the basic setup to remain as-is: there will
+   *       be a ProcNode and a WiringDescriptor, telling how it's connected to its predecessors, and
+   *       defining how the Node is supposed to operate
    */
   class WiringDescriptor
     {
-    public:
+    public: /* === public information record describing the node graph === */
       uint nrO;
       uint nrI;
       
@@ -97,6 +105,11 @@ namespace engine {
           nrI = in.size();
         }
       
+      
+      /* ==== strategy API for configuring the node operation ==== */
+      
+      friend class ProcNode;                               /////////////////////////////////TODO 1/12 : wouldn't it be better to extract that API into a distinct strategy?
+      
       /** the wiring-dependent part of the node operation.
        *  Includes the creation of a one-way state object on the stack
        *  holding the actual buffer pointers and issuing the recursive pull() calls
@@ -105,8 +118,6 @@ namespace engine {
       virtual BuffHandle
       callDown (State& currentProcess, uint requiredOutputNr)  const =0; 
       
-      friend class ProcNode;
-      
     };
   
   
@@ -120,9 +131,10 @@ namespace engine {
    *       several query/information functions. In that case, the ctor will become protected.
    *       The alternative would be to push down these information-retrieval part into a
    *       configurable element within WiringDescriptor, in which case we even might drop
-   *       ProcNode as a frontent entirely.
+   *       ProcNode as a frontend entirely.
    */
   class ProcNode
+    : boost::noncopyable
     {
       typedef mobject::Parameter<double> Param;   //////TODO: just a placeholder for automation as of 6/2008
       vector<Param> params;

tests/components/proc/engine/dispatcher-interface-test.cpp

@@ -0,0 +1,109 @@
+/*
+  DispatcherInterface(Test)  -  document and verify dispatcher for frame job creation
+
+  Copyright (C)         Lumiera.org
+    2012,               Hermann Vosseler <Ichthyostega@web.de>
+
+  This program 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.
+
+  This program 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 General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+* *****************************************************/
+
+
+#include "lib/test/run.hpp"
+#include "lib/error.hpp"
+
+//#include "proc/engine/procnode.hpp"
+#include "proc/engine/dispatcher.hpp"
+
+//#include <boost/scoped_ptr.hpp>
+//#include <iostream>
+
+using test::Test;
+//using std::cout;
+//using std::rand;
+
+
+namespace proc {
+namespace engine{
+namespace test  {
+
+  namespace { // used internally
+    
+    
+    class MockDispatcherTable
+      : public Dispatcher
+      {
+        
+      public:
+      };
+    
+#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #880
+#endif    /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #890
+      
+  } // (End) internal defs
+  
+  
+  
+  /*******************************************************************
+   * @test document and verify the engine::Dispatcher interface, used
+   *       to translate a CalcStream into individual node jobs.
+   *       This test covers the definition of the interface itself,
+   *       together with the supporting types and the default
+   *       implementation of the basic operations.
+   *       It creates and uses  a mock Dispatcher implementation.
+   */
+  class DispatcherInterface_test : public Test
+    {
+      
+      virtual void
+      run (Arg) 
+        {
+           verify_basicDispatch();
+           verify_standardDispatcherUsage();
+        }
+      
+      
+      /** @test perform the basic dispatch step
+       * and verify the generated frame coordinates
+       */
+      void
+      verify_basicDispatch()
+        {
+          
+#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #880
+#endif    /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #890
+        }
+      
+      
+      /** @test the standard invocation sequence
+       * used within the engine for planning new jobs.
+       * The actual implementation is mocked.
+       */
+      void
+      verify_standardDispatcherUsage()
+        {
+          
+#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #880
+#endif    /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #890
+        }
+    };
+  
+  
+  /** Register this test class... */
+  LAUNCHER (DispatcherInterface_test, "unit engine");
+  
+  
+  
+}}} // namespace proc::engine::test

wiki/renderengine.html

@@ -1692,11 +1692,11 @@ Taken precisely, the "degree of constriction" yields only a partial or
 As we don't have a Prolog interpreter on board yet, we utilize a mock store with preconfigured answers. (see MockConfigQuery). As this preliminary solution is lacking the ability to create new objects, we need to resort to some trickery here (please look away). The overall logic is quite broken, not to say outright idiotic, because the system isn't capable to do any real resolution — if we ignore this fact, the rest of the algorithm can be implemented, tested and used right now.
 </pre>
 </div>
-<div title="DefaultsManagement" modifier="Ichthyostega" modified="201010250138" created="200801121708" tags="def spec" changecount="13">
+<div title="DefaultsManagement" modifier="Ichthyostega" modified="201202041527" created="200801121708" tags="def spec" changecount="14">
 <pre>For several components and properties there is an implicit default value or configuration; it is stored alongside with the session. The intention is that defaults never create an error, instead, they are to be extended silently on demand. Objects configured according to these defaults can be retrieved at the [[Session]] interface by a set of overloaded functions {{{Session::current-&gt;default(Query&lt;TYPE&gt; (&quot;query string&quot;))}}}, where the //query string // defines a capability query similar to what is employed for pipes, stream types, codecs etc. This query mechanism is implemented by [[configuration rules|ConfigRules]]
 
 !!!!what is denoted by {{{default}}}?
-{{{default(Obj)}}} is a predicate expressing that the object {{{Obj}}} can be considered the default setup under the given conditions. Using the //default// can be considered as a shortcut for actually finding a exact and unique solution. The latter would require to specify all sorts of detailed properties up to the point where only one single object can satisfy all conditions. On the other hand, leaving some properties unspecified would yield a set of solutions (and the user code issuing the query had to provide means for selecting one soltution from this set). Just falling back on the //default// means that the user code actually doesn't care for any additional properties (as long as the properties he //does// care for are satisfied). Nothing is said specifically on //how//&amp;nbsp; this default gets configured; actually there can be rules //somewhere,// and, additionally, anything encountered once while asking for a default can be re-used as default under similar circumstances.
+{{{default(Obj)}}} is a predicate expressing that the object {{{Obj}}} can be considered the default setup under the given conditions. Using the //default// can be considered as a shortcut for actually finding an exact and unique solution. The latter would require to specify all sorts of detailed properties up to the point where only one single object can satisfy all conditions. On the other hand, leaving some properties unspecified would yield a set of solutions (and the user code issuing the query had to provide means for selecting one solution from this set). Just falling back on the //default// means that the user code actually doesn't care for any additional properties (as long as the properties he //does// care for are satisfied). Nothing is said specifically on //how//&amp;nbsp; this default gets configured; actually there can be rules //somewhere,// and, additionally, anything encountered once while asking for a default can be re-used as default under similar circumstances.
 &amp;rarr; [[implementing defaults|DefaultsImplementation]]</pre>
 </div>
 <div title="DesignDecisions" modifier="Ichthyostega" modified="201011210034" created="200801062209" tags="decision design discuss Concepts" changecount="33">
@@ -5776,7 +5776,7 @@ if (oldText.indexOf(&quot;SplashScreen&quot;)==-1)
 * besides, between different stream //implementation types,// there can be a ''rendering'' (lossy conversion) &amp;mdash; or no conversion at all.
 </pre>
 </div>
-<div title="StreamPrototype" modifier="Ichthyostega" modified="201106210145" created="200808152042" tags="def spec" changecount="11">
+<div title="StreamPrototype" modifier="Ichthyostega" modified="201202041524" created="200808152042" tags="def spec" changecount="14">
 <pre>The stream Prototype is part of the specification of a media stream's type. It is a semantic (or problem domain oriented) concept and should be distinguished from the actual implementation type of the media stream. The latter is provided by an [[library implementation|StreamTypeImplFacade]]. While there are some common predefined prototypes, mostly, they are defined within the concrete [[Session]] according to the user's needs. 
 
 Prototypes form an open (extensible) collection, though each prototype belongs to a specific media kind ({{{VIDEO, IMAGE, AUDIO, MIDI,...}}}).
@@ -5789,7 +5789,7 @@ Consequently, as we can't get away with an fixed Enum of all stream prototypes,
 * we can determine if another prototype is //convertible//
 
 !!Examples
-In practice, several things might be considered &quot;quite different&quot; and thus be distinguished by protorype: NTSC and PAL video, video versus digitized film, HD video versus SD video, 3D versus flat video, cinemascope versus 4:3, stereophonic versus monaural, periphonic versus panoramic sound, Ambisonics versus 5.1, dolby versus linear PCM...
+In practice, several things might be considered &quot;quite different&quot; and thus be distinguished by protorype: NTSC and PAL video, video versus digitized film, HD video versus SD video, 3D versus flat video, cinemascope versus 4:3, stereophonic versus monaural, periphonic versus panoramic sound, Ambisonics versus 5.1, data reduced ~MP3 versus full quality linear PCM...
 </pre>
 </div>
 <div title="StreamType" modifier="Ichthyostega" modified="201011071741" created="200808060244" tags="spec draft" changecount="21">