From ebf625acaea4469aa1bc325e9a096ccaa689801c Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Mon, 9 Feb 2009 02:40:57 +0100 Subject: [PATCH] cleanup and comment --- src/gui/display-service.cpp | 11 ++--------- src/gui/display-service.hpp | 25 ++++++++++++++++--------- src/include/display-facade.h | 12 ++++++------ src/include/dummy-player-facade.h | 11 +++++++---- src/proc/play/dummy-player-service.cpp | 13 +++++-------- src/proc/play/dummy-player-service.hpp | 24 +++++++++++++++--------- 6 files changed, 51 insertions(+), 45 deletions(-) diff --git a/src/gui/display-service.cpp b/src/gui/display-service.cpp index 45d38c4dd..c61dce8ee 100644 --- a/src/gui/display-service.cpp +++ b/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 -//#include -//#include - 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::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... diff --git a/src/gui/display-service.hpp b/src/gui/display-service.hpp index 3783b8dfc..2a84f9c12 100644 --- a/src/gui/display-service.hpp +++ b/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 */ diff --git a/src/include/display-facade.h b/src/include/display-facade.h index 6cabedce0..d3681a08d 100644 --- a/src/include/display-facade.h +++ b/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 diff --git a/src/include/dummy-player-facade.h b/src/include/dummy-player-facade.h index 3cbca54eb..7b4daff02 100644 --- a/src/include/dummy-player-facade.h +++ b/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 { 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; diff --git a/src/proc/play/dummy-player-service.cpp b/src/proc/play/dummy-player-service.cpp index d34288de0..18f80277b 100644 --- a/src/proc/play/dummy-player-service.cpp +++ b/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; } diff --git a/src/proc/play/dummy-player-service.hpp b/src/proc/play/dummy-player-service.hpp index 2512f38bc..8dc1f87e8 100644 --- a/src/proc/play/dummy-player-service.hpp +++ b/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);