clarify the relation of PlayProcess, CalcStream and EngineFacade

src/include/play-facade.h

@@ -100,7 +100,7 @@ namespace lumiera {
             void play(bool);          ///< play/pause toggle
             void scrub(bool);         ///< scrubbing playback
             void adjustSpeed(double); ///< playback speed control
-            void go(lib::time::Time); ///< skip to the given point in time
+            void go(time::Time);      ///< skip to the given point in time
             
             void controlPlayhead (time::Control<time::Time>     & ctrl);
             void controlDuration (time::Control<time::Duration> & ctrl);

src/lib/iter-source.hpp

@@ -339,10 +339,10 @@ namespace lib {
     
     /** pipes a given Lumiera Forward Iterator through
      *  a transformation function and wraps the resulting
-     *  transforming Iterator, exposing just a IterSource.
+     *  transforming Iterator, exposing just an IterSource.
      *  This convenience shortcut can be used to build a
      *  processing chain; the resulting IterSource will
-     *  hide any involved detail types.
+     *  hide any detail types involved.
      * @note as with any IterSource, there is one virtual
      *       function call for every fetched element.
      */

src/proc/engine/calc-stream.hpp

@@ -71,12 +71,12 @@ namespace engine{
       
       friend class EngineService;
       
+    public:
       CalcStream()
         {
-          UNIMPLEMENTED("build a calculation stream");
+          UNIMPLEMENTED("build a disabled/dead calculation stream");
         }
       
-    public:
       CalcStream (CalcStream const& o)
         { 
           UNIMPLEMENTED("clone a calculation stream");

src/proc/engine/dispatcher.hpp

@@ -40,7 +40,7 @@ namespace engine {
 //  class ExitNode;
   
   /**
-   * @todo
+   * @todo 11/11 extremely fuzzy at the moment
    */
   class Dispatcher
     {

src/proc/play/output-manager.hpp

@@ -61,6 +61,8 @@ namespace play {
   /******************************************************
    * Management of external Output connections.
    * 
+   * @todo need a concrete implementation
+   * @todo need a unit-test
    * @todo write Type comment
    */
   class OutputManager

src/proc/play/play-process.cpp

@@ -59,7 +59,8 @@ namespace play {
         throw error::State("unable to acquire a suitable output slot"   /////////////////////TICKET #197 #816
                           , LUMIERA_ERROR_CANT_PLAY);
       
-      return Feed (port,slot); //////////////////////////////////TODO: how to get the RenderConfigurator (strategy) here??? 
+      RenderConfigurator& configurator (*(RenderConfigurator*)NULL); //////////////////////////////////TODO: how to get the RenderConfigurator (strategy) here??? 
+      return Feed (port,slot,configurator); 
     }
     
     

src/proc/play/play-process.hpp

@@ -58,6 +58,7 @@
 //#include "lib/singleton-ref.hpp"
 #include "proc/mobject/model-port.hpp"
 #include "proc/play/output-manager.hpp"
+#include "proc/engine/calc-stream.hpp"
 #include "lib/iter-source.hpp"
 #include "lib/util.hpp"
 //

src/proc/play/play-service.cpp

@@ -25,7 +25,7 @@
 #include "include/play-facade.h"
 #include "proc/play/play-service.hpp"
 #include "proc/play/play-process.hpp"
-#include "lib/util.hpp"
+#include "lib/util-foreach.hpp"
 
 
 #include <string>
@@ -61,6 +61,7 @@ namespace play {
 //using std::tr1::function;
   using std::tr1::placeholders::_1;
   using util::remove_if;
+  using util::and_all;
   
   
   namespace { // hidden local details of the service implementation....
@@ -80,6 +81,8 @@ namespace play {
       typedef weak_ptr<PlayProcess> Entry;
       typedef std::vector<Entry> ProcTable;
       
+      /** @note holding just weak references
+       *  to any ongoing playback processes */
       ProcTable processes_;
       
     public:
@@ -88,13 +91,26 @@ namespace play {
       establishProcess (PlayProcess* newProcess)
         {
           lumiera::Play::Controller frontend;
+          try {
+              frontend.activate (newProcess, bind (&ProcessTable::endProcess, this, _1 ));
+            }
+          catch(...)
+            {
+              delete newProcess;
+              throw;
+            }
           
           Lock sync(this);
-          frontend.activate (newProcess, bind (&ProcessTable::endProcess, this, _1 ));
+          processes_.push_back (frontend); // keeping a weak-reference
-          processes_.push_back (frontend);
           return frontend;
         }
       
+      bool
+      isActive()  const
+        {
+          return ! and_all (processes_, isDead);
+        }
+      
     private:
       void
       endProcess (PlayProcess* dyingProcess)
@@ -118,9 +134,13 @@ namespace play {
   
   
   PlayService::~PlayService()
+    {
+      if (pTable_->isActive())
         {
           UNIMPLEMENTED ("block waiting for any ongoing play processes. Ensure the process table is empty -- OR -- hand it over to some kind of cleanup service");
         }
+      ENSURE (!pTable_->isActive());
+    }
   
   
   /** bring up the global render- and playback service.
@@ -195,7 +215,7 @@ namespace lumiera {
   Play::Controller
   Play::perform(Viewer)
   {
-    UNIMPLEMENTED ("build PlayProcess directly for a Viwer element");
+    UNIMPLEMENTED ("build PlayProcess directly for a Viewer element");
   }
   
   

src/proc/play/play-service.hpp

@@ -21,10 +21,33 @@
 */
 
 /** @file play-service.hpp
- ** Player subsystem......
+ ** Primary service of the Player subsystem: Starting and controlling render/playback.
+ ** This is the implementation level service interface for the "Player". Client code
+ ** should access this service through the lumiera::Play facade interface.
+ ** 
+ ** The player and render control subsystem allows to start and control playback and
+ ** rendering at any given collection of model ports (the conceptual exit points
+ ** of the High-Level-Model). These model ports are the (side effect) result of a
+ ** build process performed on the High-Level-Model, causing all nominal output
+ ** designations within the model to be resolved as far as possible. Additionally,
+ ** for \em playback, the global level of the model (the global pipes of a timeline)
+ ** need to be connected to a viewer component. This results in a further resolution
+ ** step, mapping the output designations to the concrete output possibilities of
+ ** the running Lumiera instance. This mapping information is kept embedded within
+ ** an OutputManager instance, passed as parameter when invoking the player service.
+ ** Alternatively, for \em rendering, a similar kind of output mapping information
+ ** needs to be provided, again embedded within an OutputManager instance, this
+ ** time leading to an output file to be rendered.
+ ** 
+ ** The result of an invocation of the Player service is a Play::Controller
+ ** frontend object. This smart-ptr like handle can be used by the client to
+ ** control all aspects of playback or rendering; it behaves like a state machine.
+ ** When the last copy of this Play::Controller frontend goes out of scope, behind
+ ** the scenes the corresponding PlayProcess gets terminated and prepared for cleanup. 
+ ** 
+ ** @see engine::EngineService
+ ** @todo WIP-WIP-WIP as of Nov.2011
  ** 
- ** @see lumiera::DummyPlayer
- ** @see gui::PlaybackController usage example 
  */
 
 

src/proc/play/render-configurator.cpp

@@ -53,16 +53,19 @@ namespace play {
       : public RenderConfigurator
       {
         
-        RenderStreams
+        Feed::RenderStreams
         buildCalculationStreams (ModelPort port, OutputSlot& output)
           {
             UNIMPLEMENTED("build an active playback/render feed");
+#if false /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #832
             
             ///TODO allocate the output slot
             ///TODO extract the individual channels
             ///TODO get the timings
+            ///TODO define the Quality
             
             engine::EngineService::instance().calculate(port, nominalTimings, activeOutputConnection, serviceQuality);
+#endif    /////////////////////////////////////////////////////////////////////////////////////////////////////////////UNIMPLEMENTED :: TICKET #832
           }
       };
   

src/proc/play/render-configurator.hpp

@@ -40,6 +40,7 @@
 //#include "common/instancehandle.hpp"
 //#include "lib/singleton-ref.hpp"
 #include "proc/mobject/model-port.hpp"
+#include "proc/play/play-process.hpp"
 //#include "proc/play/output-manager.hpp"
 //#include "lib/iter-source.hpp"
 //#include "lib/util.hpp"
@@ -74,9 +75,7 @@ namespace play {
       virtual ~RenderConfigurator();  ///< this is an interface
       
       
-      typedef std::vector<engine::CalcStream> RenderStreams;  ////TODO this belongs rather into class Feed
+      virtual Feed::RenderStreams buildCalculationStreams (ModelPort, OutputSlot&)  =0;
-      
-      virtual RenderStreams buildCalculationStreams (ModelPort, OutputSlot&)  =0;
       
     };
     

wiki/renderengine.html

@@ -1376,6 +1376,25 @@ at the lowest level within the builder there is the step of building a //connect
 * by default, a timeline is outfitted with one video and one sound master bus
 </pre>
 </div>
+<div title="CalcStream" modifier="Ichthyostega" modified="201112162336" created="201112162053" tags="spec Rendering" changecount="7">
+<pre>Calculation stream is an organisational unit used at the interface level of the Lumiera engine.
+Representing a //stream of calculations,// delivering generated data within //timing constraints,// it is used
+*by the [[play process(es)|PlayProcess]] to define and control properties of the output generation
+*at the engine backbone to feed the [[Scheduler]] with individual [[render jobs|RenderJob]] to implement this stream of calculations
+Calculation stream objects are stateless, constant chunks of definition -- any altering of playback or rendering parameters just causes the respective descriptors to be superseeded. The presence of a CalcStream (being alive within the denoted time span) implies that using any of the associated jobs, dispatcher tables, node and wiring descriptors is safe
+
+!lifecycle
+Calculation stream descriptors can be default constructed, representing a //void calculation.// You can't do anything with these.
+Any really interesting calculation stream needs to be retrieved from the EngineFaçade. Additionally, an existing calculation stream can be chained up or superseded, yielding a new CalcStream based on the parameters of the existing one, possibly with some alterations.
+
+!purpose
+When a calculation stream is retrieved from the EngineFaçade it is already registered and attached there and represents an ongoing activity. Under the hood, several further collaborators will hold a copy of that calculation stream descriptor. While, as such, a CalcStream has no explicit state, at any time it //represents a current state.// In case the running time span of that stream is limited, it becomes superseded automatically, just by the passing of time.
+
+Each calculation stream refers a relevant [[frame dispatcher table|FrameDispatcher]]. Thus, for the engine (interface level), the calculation stream allows to produce the individual [[render jobs|RenderJob]] to enqueue with the [[Scheduler]]. This translation step is what links and relates nominal time with running wall clock time, thereby obeying the [[timing constraints|Timings]] given while initially defining the calculation stream.
+
+Additionally, each calculation stream knows how to access a //render environment closure,// allowing to re-schedule and re-adjust the setup of this stream. Basically, this closure is comprised of several functors (callbacks), which could be invoked to perform management tasks later on. Amongst others, this allows the calculation stream to redefine, supersede or &quot;cancel itself&quot;, without the need to access a central registration table at the engine interface level.
+</pre>
+</div>
 <div title="ColorPalette" modifier="Ichthyostega" modified="200807131329" created="200706190033" tags="excludeMissing" changecount="14">
 <pre>Background: #fefefd
 Foreground: #000
@@ -1973,12 +1992,12 @@ The fixture is like a grid, where one dimension is given by the [[model ports|Mo
 :Thus the exit nodes are keyed by ~Pipe-ID as well (and consequently have a distinct [[stream type|StreamType]]) -- each model port coresponds to {{{&lt;number_of_segments&gt;}}} separate exit nodes, but of course an exit node may be //mute.//
 </pre>
 </div>
-<div title="FixtureDatastructure" modifier="Ichthyostega" modified="201109031600" created="201012162304" tags="spec Builder" changecount="11">
+<div title="FixtureDatastructure" modifier="Ichthyostega" modified="201112162317" created="201012162304" tags="spec Builder" changecount="12">
 <pre>Generally speaking, the datastructure to implement the ''Fixture'' (&amp;rarr; see a more general description [[here|Fixture]]) is comprised of a ModelPortRegistry and a set of [[segmentations|Segmentation]] per Timeline.
 This page focusses on the actual data structure and usage details on that level. See also &amp;rarr; [[storage|FixtureStorage]] considerations.
 
 !transactional switch
-A key point to note is the fact that the fixture is frequently [[re-built||BuildFixture]] by the [[Builder]], while render processes may be going on in parallel. Thus, when a build process is finished, a transactional ''commit'' happens to ''hot swap'' the new parts of the model. This is complemented by a clean-up of tainted render processes; finally, storage can be reclaimed.
+A key point to note is the fact that the fixture is frequently [[re-built|BuildFixture]] by the [[Builder]], while render processes may be going on in parallel. Thus, when a build process is finished, a transactional ''commit'' happens to ''hot swap'' the new parts of the model. This is complemented by a clean-up of tainted render processes; finally, storage can be reclaimed.
 
 To support this usage pattern, the Fixture implementation makes use of the [[PImpl pattern|http://c2.com/cgi/wiki?PimplIdiom]]
 
@@ -4386,13 +4405,13 @@ We need a way of addressing existing [[pipes|Pipe]]. Besides, as the Pipes and T
 &lt;&lt;tasksum end&gt;&gt;
 </pre>
 </div>
-<div title="PlayProcess" modifier="Ichthyostega" modified="201108141652" created="201012181714" tags="def spec Player img" changecount="14">
+<div title="PlayProcess" modifier="Ichthyostega" modified="201112092000" created="201012181714" tags="def spec Player img" changecount="16">
 <pre>With //play process//&amp;nbsp; we denote an ongoing effort to calculate a stream of frames for playback or rendering.
 The play process is an conceptual entity linking together several activities in the [[Backend]] and the RenderEngine. Creating a play process is the central service provided by the [[player subsystem|Player]]: it maintains a registration entry for the process to keep track of associated entities, resources allocated and calls [[dispatched|FrameDispatcher]] as a consequence, and it wires and exposes a PlayController to serve as an interface and information hub.
 
 ''Note'': the player is in no way engaged in any of the actual calculation and management tasks necessary to make this [[stream of calculations|CalcStream]] happen. The play process code contained within the player subsystem is largely comprised of organisational concerns and not especially performance critical.
-* the [[Backend]] is responsible for scheduling and [[dispatching|Dispatcher]] the [[calculation stream|CalcStream]]
+* the [[Backend]] is responsible for [[dispatching|Dispatcher]] the [[calculation stream|CalcStream]] and scheduling individual calculation jobs
-* the RenderEngine has the ability to cary out individual frame calculations
+* the RenderEngine has the ability to carry out individual frame calculations
 * the OutputSlot exposed by the [[output manager|OutputManagement]] is responsible for accepting timed frame delivery
 
 [&gt;img[Anatomy of a Play Process|uml/fig144005.png]]
@@ -4402,7 +4421,7 @@ The Controller is exposed to the client and acts as frontend handle, while the p
 Right within the play process, there is a separation into two realms, relying on different programming paradigms. Obviously the play controller is a state machine, and similarily the body object (play process) has a distinct operation state. Moreover, the current collection of individual objects hooked up at any given instance is a stateful variable. To the contrary, when we enter the realm of actual processing, operations are carried out in parallel, relying on stateless descriptor objects, wired into individual calculation jobs, to be scheduled as non-blocking units of operation. For each series of consecutive frames to be calculated, there is a descriptor object, the CalcStream, which also links to a specificaly tailored dispatcher table, allowing to schedule the individual frame jobs. Whenever the controller determines a change in the playback plan (speed change, skip, scrubbing, looping, ...), a new CalcStream is created, while the existing one is just used to mark any not-yet processed job as superseded.
 </pre>
 </div>
-<div title="PlayService" modifier="Ichthyostega" modified="201105221918" created="201105221900" tags="Player spec draft" changecount="9">
+<div title="PlayService" modifier="Ichthyostega" modified="201112161614" created="201105221900" tags="Player spec draft" changecount="11">
 <pre>The [[Player]] is an independent [[Subsystem]] within Lumiera, located at Proc-Layer level. A more precise term would be &quot;rendering and playback coordination subsystem&quot;. It provides the capability to generate media data, based on a high-level model object, and send this generated data to an OutputDesignation, creating an continuous and timing controlled output stream. Clients may utilise these functionality through the ''play service'' interface.
 
 !provided services
@@ -4415,7 +4434,7 @@ This is the core service provided by the player subsystem. The purpose is to cre
 ;data producers
 :a set of ModelPort elements to ''pull'' for generating output. They can either be handed in direcly, or resolved from a set of OutputDesignation elements
 ;data sinks
-:to be able to create output, the PlayProcess needs to cooperate with OutputSlot.s
+:to be able to create output, the PlayProcess needs to cooperate with [[output slots|OutputSlot]]
 :physical outputs are never handled directly, rather, the playback or rendering needs an OutputManager to resolve the output designations into output slots
 ;controller
 :when provided with these two prerequisites, the play service is able to build a PlayProcess.
@@ -4425,16 +4444,16 @@ This is the core service provided by the player subsystem. The purpose is to cre
 :any details of this processing remain opaque for the clients; even the player subsystem just accesses the EngineFaçade
 </pre>
 </div>
-<div title="Player" modifier="Ichthyostega" modified="201106131443" created="201012181700" tags="def overview" changecount="10">
+<div title="Player" modifier="Ichthyostega" modified="201112091904" created="201012181700" tags="def overview" changecount="13">
 <pre>Within Lumiera, &amp;raquo;Player&amp;laquo; is the name for a [[Subsystem]] responsible for organising and tracking //ongoing playback and render processes.// &amp;rarr; [[PlayProcess]]
 The player subsystem does not perform or even manage any render operations, nor does it handle the outputs directly.
-Yet it adresses some central concerns:
+Yet it addresses some central concerns:
 
 ;uniformity
 :all playback and render processes are on equal footing, handled in a similar way.
 ;integration
 :the player cares for the necessary integration with the other subsystems
-:it consults the OutputManagement, retrieves the necessary informations from the [[Session]] and coordinates [[Backend]] calls.
+:it consults the OutputManagement, retrieves the necessary informations from the [[Session]] and coordinates the forwarding of [[Backend]] calls.
 ;time quantisation
 :the player translates continuous time values into discrete frame counts.
 :to perform this [[quantisation|TimeQuant]], the help of the session for building a TimeGrid for each output channel is required.
@@ -5132,8 +5151,8 @@ __see also__
 &amp;rarr; the protocol [[how to operate the nodes|NodeOperationProtocol]]
 </pre>
 </div>
-<div title="RenderProcess" modifier="Ichthyostega" modified="201007170307" created="200706190705" tags="Rendering operational" changecount="28">
+<div title="RenderProcess" modifier="Ichthyostega" modified="201112162056" created="200706190705" tags="Rendering operational" changecount="29">
-<pre>For each segment (of the effective timeline), there is a Processor holding the exit node(s) of a processing network, which is a &quot;Directed Acyclic Graph&quot; of small, preconfigured, stateless [[processing nodes|ProcNode]]. This network is operated according to the ''pull principle'', meaning that the rendering is just initiated by &quot;pulling&quot; output from the exit node, causing a cascade of recursive downcalls or prerequisite calculations to be scheduled as separate jobs. Each node knows its predecessor(s), thus the necessary input can be pulled from there. Consequently, there is no centralized &quot;engine object&quot; which may invoke nodes iteratively or table driven &amp;mdash; rather, the rendering can be seen as a passive service provided for the backend, which may pull from the exit nodes at any time, in any order (?), and possibly multithreaded.
+<pre>For each segment (of the effective timeline), there is a Processor holding the exit node(s) of a processing network, which is a &quot;Directed Acyclic Graph&quot; of small, preconfigured, stateless [[processing nodes|ProcNode]]. This network is operated according to the ''pull principle'', meaning that the rendering is just initiated by &quot;pulling&quot; output from the exit node, causing a cascade of recursive downcalls or prerequisite calculations to be scheduled as individual [[jobs|RenderJob]]. Each node knows its predecessor(s), thus the necessary input can be pulled from there. Consequently, there is no centralized &quot;engine object&quot; which may invoke nodes iteratively or table driven &amp;mdash; rather, the rendering can be seen as a passive service provided for the backend, which may pull from the exit nodes at any time, in any order (?), and possibly multithreaded.
 All State necessary for a given calculation process is encapsulated and accessible by a StateProxy object, which can be seen as the representation of &quot;the process&quot;. At the same time, this proxy provides the buffers holding data to be processed and acts as a gateway to the backend to handle the communication with the Cache. In addition to this //top-level State,// each calculation step includes a small [[state adapter object|StateAdapter]] (stack allocated), which is pre-configured by the builder and serves the purpose to isolate the processing function from the detals of buffer management.
 
 
@@ -5167,8 +5186,8 @@ Later on we expect a distinct __query subsystem__ to emerge, presumably embeddin
 
 &amp;rarr; QuantiserImpl</pre>
 </div>
-<div title="SchedulerRequirements" modifier="Ichthyostega" created="201107080145" tags="Rendering spec draft discuss" changecount="1">
+<div title="SchedulerRequirements" modifier="Ichthyostega" modified="201112162055" created="201107080145" tags="Rendering spec draft discuss" changecount="3">
-<pre>The Scheduler is responsible for geting the individual render jobs to run. The basic idea is that individual render jobs //should never block// -- and thus the calculation of a single frame might be split into several jobs, including resource fetching. This, together with the data exchange protocol defined for the OutputSlot, and the requirements of storage management (especially releasing of superseded render nodes), leads to certain requirements to be ensured by the scheduler:
+<pre>The [[Scheduler]] is responsible for geting the individual [[render jobs|RenderJob]] to run. The basic idea is that individual render jobs //should never block// -- and thus the calculation of a single frame might be split into several jobs, including resource fetching. This, together with the data exchange protocol defined for the OutputSlot, and the requirements of storage management (especially releasing of superseded render nodes), leads to certain requirements to be ensured by the scheduler:
 ;ordering of jobs
 :the scheduler has to ensure all prerequisites of a given job are met
 ;job time window