cleanup and comment

src/gui/display-service.cpp

@@ -22,28 +22,21 @@
 
 
 #include "gui/display-service.hpp"
-//#include "lib/singleton.hpp"
 
 extern "C" {
 #include "common/interfacedescriptor.h"
 }
 
-#include <string>
-//#include <memory>
-//#include <boost/scoped_ptr.hpp>
-
 
 namespace gui {
   
-  using std::string;
-//    using boost::scoped_ptr;
   
   
   namespace { // hidden local details of the service implementation....
     
     
     
-    /* ================== define an lumieraorg_GuiNotification instance ======================= */
+    /* ================== define an lumieraorg_Display instance ======================= */
     
     LUMIERA_INTERFACE_INSTANCE (lumieraorg_interfacedescriptor, 0
                                ,lumieraorg_DisplayFacade_descriptor
@@ -118,7 +111,7 @@ namespace gui {
     using lumiera::facade::LUMIERA_ERROR_FACADE_LIFECYCLE;
     typedef lib::SingletonRef<DisplayService>::Accessor InstanceRef;
     
-    InstanceRef _instance; ///< a backdoor for the C Language impl to access the actual DummyPlayer implementation...
+    InstanceRef _instance; ///< a backdoor for the C Language impl to access the actual DisplayService implementation...
     
     
     

src/gui/display-service.hpp

@@ -21,17 +21,24 @@
 */
 
 /** @file display-service.hpp
- ** A public service provided by the GUI, implementing the gui::GuiNotification facade interface.
- ** The purpose of this service is to push state update and notification of events from the lower
- ** layers into the Lumiera GUI. Typically, this happens asynchronously and triggered by events
- ** within the lower layers.
+ ** A public service provided by the GUI, implementing the lumiera::Display facade interface.
+ ** It serves two purposes: 
+ ** - It maintains a collection of DisplayerSlot objects, which are the actual connection points
+ **   and allow to receive frames and dispatch them to the GTK main event loop thread.
+ **   Conceptually, creating such a slot means providing a possible display for output.
+ ** - It provides the actual implementation of the Display facade interface, i.e. the function
+ **   which is to invoked periodically by the playback processes to dispose a new frame into
+ **   the display.
  ** 
- ** This service is the implementation of a layer separation facade interface. Clients should use
- ** proc::play::DummyPlayer#facade to access this service. This header defines the interface used
- ** to \em provide this service, not to access it.
+ ** This service is the implementation of a layer separation facade interface. This header defines
+ ** the interface used to \em provide this service, not to access it. Clients get a specific
+ ** LumieraDisplaySlot passed as parameter when initiating a playback process from the GUI. Using
+ ** this LumieraDisplaySlot handle, clients should then use  lumiera::DummyPlayer#facade to access
+ ** an implementation instance of this service in order to push actual frames up.
  **
- ** @see gui::GuiFacade
- ** @see guifacade.cpp starting this service 
+ ** @see lumiera::Display
+ ** @see lumiera::DummyPlayer
+ ** @see gui::PlaybackController usage example 
  */
 
 

src/include/display-facade.h

@@ -21,7 +21,7 @@
 */
 
 /** @file display-facade.hpp
- ** Major public Interface of the Lumiera GUI. While generally speaking, the GUI
+ ** Major public Interface of the Lumiera GUI. While, generally speaking, the GUI
  ** controls the application and thus acts on its own, it exposes some services
  ** to the lower layers. Especially the lumiera::Display interface serves to
  ** hand over calculated frames to the GUI for displaying them in a viewer.
@@ -64,9 +64,6 @@ typedef lumiera_displaySlot* LumieraDisplaySlot;
 namespace lumiera {
   
   
-//  class ProcessImpl;
-  
-  
   /******************************************************************
    * Interface for outputting frames to an (already allocated) viewer
    * or display. The viewer is addressed by an "slot" handle, which the 
@@ -108,6 +105,9 @@ namespace lumiera {
         {
           
         public:
+          /** push a frame up to the display, calling
+           *  through the CL Interface.
+           *  @see DisplayService::allocate */
           inline void
           operator() (LumieraDisplayFrame frame)
             {
@@ -126,8 +126,8 @@ namespace lumiera {
       virtual ~Display();
     };
   
-    
-
+  
+  
   
 } // namespace lumiera
 

src/include/dummy-player-facade.h

@@ -79,11 +79,13 @@ namespace lumiera {
         /**
          * Continuous playback process, which has been started with a specific
          * output size, format and framerate. It is a handle to a calculation process,
-         * which is about to produce a stream of frames to be retrieved by calling
-         * the #getFrame function on this handle.
+         * which is about to produce a stream of frames and push them to the viewer widget,
+         * specified by a LumieraDisplaySlot when starting this process.
          * 
          * The Lifecycle of the referred playback process is managed automatically
-         * through this handle (by ref count).
+         * through this handle (by ref count). Client code is supposed to use the
+         * API on this handle to control the playback mode.
+         * 
          * @see handle.hpp 
          * @see dummy-player-service.cpp implementation
          */
@@ -91,12 +93,13 @@ namespace lumiera {
           : public lib::Handle<proc::play::ProcessImpl>
           {
           public:
-            void        play(bool);
+            void play(bool); ///< play/pause toggle
           };
         
         
         //////////////////TODO: define some dummy negotiation about size and framerate....
         
+        /** create a new playback process outputting to the given viewer/display */
         virtual Process start(LumieraDisplaySlot viewerHandle)   =0;
         
         

src/proc/play/dummy-player-service.cpp

@@ -79,17 +79,14 @@ namespace proc  {
           void
           triggerShutdown ()  throw()
             {
-              TODO ("implement waiting for any playback processes to terminate gracefully");
-              //..... but this would require us to use a separate thread, so I skip it for now.
-              //      Probably it's better design to manage the processes in a separate thread anyway...
-              
               thePlayer_.reset(0);
+              // note: shutdown of the DummyPlayerService instance may block
+             //        for a short period, until termination of all tick services
             }
           
           bool 
           checkRunningState ()  throw()
             {
-              //note: not locking here...
               return (thePlayer_);
             }
         };
@@ -100,7 +97,7 @@ namespace proc  {
       
       
       
-      /* ================== define an lumieraorg_GuiNotification instance ======================= */
+      /* ================== define an lumieraorg_DummyPlayer instance ======================= */
       
       LUMIERA_INTERFACE_INSTANCE (lumieraorg_interfacedescriptor, 0
                                  ,lumieraorg_DummyPlayerFacade_descriptor
@@ -294,7 +291,7 @@ namespace proc  {
     
     
     void
-    ProcessImpl::terminate (ProcessImpl* process)
+    ProcessImpl::terminate (ProcessImpl* process)  ///< deleter function for lib::Handle
     {
       if (process)
         delete process;
@@ -306,7 +303,7 @@ namespace proc  {
     ProcessImpl::createHandle()
     {
       DummyPlayer::Process handle;
-      handle.activate(this, &terminate);
+      handle.activate(this, &terminate);  // note the deleter function...
       return handle;
     }
     

src/proc/play/dummy-player-service.hpp

@@ -20,18 +20,20 @@
  
 */
 
-/** @file notification-service.hpp
- ** A public service provided by the GUI, implementing the gui::GuiNotification facade interface.
- ** The purpose of this service is to push state update and notification of events from the lower
- ** layers into the Lumiera GUI. Typically, this happens asynchronously and triggered by events
- ** within the lower layers.
+/** @file dummy-player-service.hpp
+ ** A public service provided by the Proc-Layer, implementing a dummy/mockup playback process.
+ ** This is a design sketch; Lumiera isn't able to generate rendered output as of 2/2009. The
+ ** idea is, that for each ongoing calculation process, there is a ProcessImpl instance holding
+ ** the necessary handles and allocations and providing an uniform API to the client side.
+ ** Especially, this ProcessImpl holds a TickService, which generates periodic callbacks, and
+ ** it uses an output handle (functor) to push the generated frames up.
  ** 
  ** This service is the implementation of a layer separation facade interface. Clients should use
  ** proc::play::DummyPlayer#facade to access this service. This header defines the interface used
  ** to \em provide this service, not to access it.
  **
- ** @see gui::GuiFacade
- ** @see guifacade.cpp starting this service 
+ ** @see lumiera::DummyPlayer
+ ** @see gui::PlaybackController usage example 
  */
 
 
@@ -86,9 +88,10 @@ namespace proc {
         ProcessImpl(LumieraDisplaySlot) ;
        ~ProcessImpl() ;
         
-        /* Implementation-level API to be used By DummyPlayerService */
         
-        /** activate a playback process 
+        /* Implementation-level API */
+        
+        /** activate a playback process
          *  with given specification */
         void setRate (uint fps);
         
@@ -97,6 +100,9 @@ namespace proc {
         
         void  doPlay(bool yes);
         
+        
+        /* Lifecycle */
+        
         DummyPlayer::Process createHandle();
         static void terminate(ProcessImpl* process);