From df46c3f9013f6d1c3334da7df373c669a79757b6 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Wed, 9 Nov 2016 23:40:46 +0100 Subject: [PATCH] Doxygen: fill in missing file level headlines for Proc-Layer (Player) --- src/proc/play/dummy-play-connection.cpp | 2 +- src/proc/play/dummy-play-connection.hpp | 28 ++++++++++++------------- src/proc/play/dummy-player-service.cpp | 2 +- src/proc/play/output-director.cpp | 2 +- src/proc/play/output-slot.cpp | 2 +- src/proc/play/output-slot.hpp | 10 ++++----- src/proc/play/play-process.cpp | 2 +- src/proc/play/play-service.cpp | 2 +- src/proc/play/play-service.hpp | 7 ++++--- src/proc/play/render-configurator.cpp | 4 +++- src/proc/play/render-configurator.hpp | 2 +- src/proc/play/sound/jack-output.cpp | 4 +++- src/proc/play/sound/jack-output.hpp | 4 +++- src/proc/play/timings.cpp | 6 +++++- 14 files changed, 44 insertions(+), 33 deletions(-) diff --git a/src/proc/play/dummy-play-connection.cpp b/src/proc/play/dummy-play-connection.cpp index afaad279e..120c0186e 100644 --- a/src/proc/play/dummy-play-connection.cpp +++ b/src/proc/play/dummy-play-connection.cpp @@ -22,7 +22,7 @@ /** @file dummy-play-connection.cpp - ** TODO dummy-play-connection.cpp + ** Implementation of a service for mock render playback to support testing. */ diff --git a/src/proc/play/dummy-play-connection.hpp b/src/proc/play/dummy-play-connection.hpp index 45ca8048a..a48cf3c5f 100644 --- a/src/proc/play/dummy-play-connection.hpp +++ b/src/proc/play/dummy-play-connection.hpp @@ -21,7 +21,7 @@ */ /** @file dummy-play-connection.hpp - ** Dummy and test setup of playback and rendering, \em omitting most of the Lumiera engine. + ** Dummy and test setup of playback and rendering, _omitting most_ of the Lumiera engine. ** Building this dummy configuration was driven by the need to test and verify the design ** in the course of building the foundations of the render engine. The design of Lumiera's ** engine is elaborate, and thus -- for a long time -- we have to live with a not-yet @@ -32,7 +32,7 @@ ** these placeholders are connected, allowing to produce specific test situations and then ** verify the results after the test run. ** - ** \par Use cases + ** # Use cases ** This dummy setup can be used in various circumstances ** - for unit tests we want to produce artificial test media frames: each TestFrame is ** produced with a reproducible pseudo-random sequence and can be verified to the last bit. @@ -44,16 +44,16 @@ ** to verify a more complicated wiring setup. Thus, the DummyPlayConnection is there to stay! ** ** Because these are somewhat similar usage scenarios, where this and that part is to be exchanged - ** for some, we prefer a policy based design here: The DummyPlayConnection is templated - ** to use a \em strategy, filling in the variable parts. + ** for some, we prefer a _policy based design_ here: The DummyPlayConnection is templated + ** to use _a strategy,_ filling in the variable parts. ** - ** \par provided test services + ** # provided test services ** By using different strategy template parameters, we create different flavours of the dummy; ** each one counting as a separate setup (not related to each other, that is). The actual instance ** then can just be default created; it should be placed into an scope enduring the whole usage ** cycle. Repeated re-initialisation or re-loading is outside the intended usage scope here. ** - ** The core interface allows to retrieve dummy implementations of + ** The *core interface* allows to retrieve dummy implementations of ** - a session model exposing exit node(s) ** - generator object(s) to live within this session model ** - corresponding generator nodes to serve as implementation of the former @@ -61,9 +61,9 @@ ** - OutputSlot implementations to serve as pseudo- or demo output facilities ** - an OutputManager exposing those output facilities. ** - ** The test support interface provides a test driver for performing a controlled + ** The *test support interface* provides a test driver for performing a controlled ** playback or rendering for some time. Thus, a test routine may lock into a blocking wait, - ** to investigate results after the planned test sequence was performed. + ** to investigate results after the planned test sequence was performed. ** ** @see lumiera::DummyPlayer ** @see gui::PlaybackController usage example @@ -129,10 +129,10 @@ namespace play { // using lib::ScopedCollection; // using lib::Literal; using lib::eachEntry; - + typedef asset::ID PID; typedef asset::ID TID; - + // typedef ModelPortRegistry::ModelPortDescriptor const& MPDescriptor; @@ -153,7 +153,7 @@ namespace play { const string namePortB("bus-B"); /** - * helper for dummy render engine: + * helper for dummy render engine: * Simulate the result of a build process, * without actually running the builder. * Produces some mock pipes, model ports etc. @@ -208,7 +208,7 @@ namespace play { } }; } - + /****************************************************************//** * Framework for dummy playback and rendering. @@ -216,7 +216,7 @@ namespace play { * allowing to start a data producing process while leaving out * various parts of the real engine implementation. The specific * mode of operation, suitable for various test scenarios, may be - * fine tuned by the strategy object defined as template parameter. + * fine tuned by the strategy object defined as template parameter. */ template class DummyPlayConnection @@ -274,4 +274,4 @@ namespace play { }} // namespace proc::play -#endif +#endif /*PROC_PLAY_DUMMY_PLAY_CONNECTION_H*/ diff --git a/src/proc/play/dummy-player-service.cpp b/src/proc/play/dummy-player-service.cpp index 04f227498..2e3e829d2 100644 --- a/src/proc/play/dummy-player-service.cpp +++ b/src/proc/play/dummy-player-service.cpp @@ -22,7 +22,7 @@ /** @file dummy-player-service.cpp - ** TODO dummy-player-service.cpp + ** Implementation of a service for mock render output to support testing. */ diff --git a/src/proc/play/output-director.cpp b/src/proc/play/output-director.cpp index bd6f85dfd..171a349dd 100644 --- a/src/proc/play/output-director.cpp +++ b/src/proc/play/output-director.cpp @@ -22,7 +22,7 @@ /** @file output-director.cpp - ** TODO output-director.cpp + ** Implementation of global output connection management */ diff --git a/src/proc/play/output-slot.cpp b/src/proc/play/output-slot.cpp index 723aeb8a6..15e50f999 100644 --- a/src/proc/play/output-slot.cpp +++ b/src/proc/play/output-slot.cpp @@ -22,7 +22,7 @@ /** @file output-slot.cpp - ** TODO output-slot.cpp + ** Generic implementation functionality common to all output connections. */ diff --git a/src/proc/play/output-slot.hpp b/src/proc/play/output-slot.hpp index cc93f08ef..3d99c1589 100644 --- a/src/proc/play/output-slot.hpp +++ b/src/proc/play/output-slot.hpp @@ -32,7 +32,7 @@ ** external output, or a group of such outputs (e.g. left and right sound card output channels), ** or an output file or similar capability accepting media content. Initially, an output slot ** needs to be provided, configured and registered, using an implementation suitable for the - ** kind of media data to be output (sound, video) and also suitable for the special circumstances + ** kind of media data to be sent (sound, video) and also suitable for the special circumstances ** of the output capability (render a file, display video in a GUI widget, send video to some ** full screen display, establish a Jack port, just use some kind of "sound out"). An output ** slot is always limited to a single kind of media, and to a single connection unit, but @@ -43,16 +43,16 @@ ** there may be only a single client using a given output slot this way. To stress this point: ** output slots don't provide any kind of inherent mixing capability; any adaptation, mixing, ** overlaying and sharing needs to be done within the nodes network producing the output data - ** to be fed into the slot. (in special cases, some external output capabilities — e.g. the - ** Jack audio connection system — may still provide additional mixing capabilities, + ** to be fed into the slot. (in special cases, some external output capabilities -- e.g. the + ** Jack audio connection system -- may still provide additional mixing capabilities, ** but that's beyond the scope of the Lumiera application) ** ** Once allocated, the output slot returns a set of concrete sink handles (one for each ** physical channel expecting data). The calculating process feeds its results into those handles. ** Size and other characteristics of the data frames are assumed to be suitable, which typically ** won't be verified at that level anymore. Besides that, the allocation of an output slot reveals - ** detailed timing expectations. The client is required to comply to these timings when \em emitting - ** data — he's even required to provide a current time specification, alongside with the data. + ** detailed timing expectations. The client is required to comply to these timings when _emitting_ + ** data -- he's even required to provide a current time specification, alongside with the data. ** Based on this information, the output slot has the ability to handle timing failures gracefully; ** the concrete output slot implementation is expected to provide some kind of de-click or ** de-flicker facility, which kicks in automatically when a timing failure is detected. diff --git a/src/proc/play/play-process.cpp b/src/proc/play/play-process.cpp index 9d32fecf8..e069b38d6 100644 --- a/src/proc/play/play-process.cpp +++ b/src/proc/play/play-process.cpp @@ -22,7 +22,7 @@ /** @file play-process.cpp - ** TODO play-process.cpp + ** Implementation to organise an ongoing playback/rendering process */ diff --git a/src/proc/play/play-service.cpp b/src/proc/play/play-service.cpp index be686e971..af072bc4f 100644 --- a/src/proc/play/play-service.cpp +++ b/src/proc/play/play-service.cpp @@ -22,7 +22,7 @@ /** @file play-service.cpp - ** TODO play-service.cpp + ** Implementation of core parts of the Player subsystem */ diff --git a/src/proc/play/play-service.hpp b/src/proc/play/play-service.hpp index 491bee8fb..dec178e91 100644 --- a/src/proc/play/play-service.hpp +++ b/src/proc/play/play-service.hpp @@ -30,12 +30,12 @@ ** 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) + ** for _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 + ** Alternatively, for _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. ** @@ -46,7 +46,8 @@ ** the scenes the corresponding PlayProcess gets terminated and prepared for cleanup. ** ** @see engine::EngineService - ** @todo WIP-WIP-WIP as of Nov.2011 + ** @todo started as draft in 11/2011 + ** @todo as of 2016 development in this area is stalled, but the design done thus far valid ** */ diff --git a/src/proc/play/render-configurator.cpp b/src/proc/play/render-configurator.cpp index 603bfb113..ecbadc4e6 100644 --- a/src/proc/play/render-configurator.cpp +++ b/src/proc/play/render-configurator.cpp @@ -22,7 +22,9 @@ /** @file render-configurator.cpp - ** TODO render-configurator.cpp + ** Implementation functionality to bridge between engine::PlayService and engine::EngineService. + ** The former allows to start playback (or rendering) as a high-level activity, while the latter + ** can manage and perform [calculation streams](\ref CalcStream) */ diff --git a/src/proc/play/render-configurator.hpp b/src/proc/play/render-configurator.hpp index c3c88910e..0214aff13 100644 --- a/src/proc/play/render-configurator.hpp +++ b/src/proc/play/render-configurator.hpp @@ -21,7 +21,7 @@ */ /** @file render-configurator.hpp - ** Strategy holding all the detail knowledge necessary to establish + ** Strategy to hold all the detail knowledge necessary to establish ** a running render CalculationStream. ** ** @see engine::EngineService diff --git a/src/proc/play/sound/jack-output.cpp b/src/proc/play/sound/jack-output.cpp index de7f7831a..85f857387 100644 --- a/src/proc/play/sound/jack-output.cpp +++ b/src/proc/play/sound/jack-output.cpp @@ -22,7 +22,9 @@ /** @file jack-output.cpp - ** TODO jack-output.cpp + ** + ** @todo empty placeholder: yes we will support Jack Audio! + ** */ diff --git a/src/proc/play/sound/jack-output.hpp b/src/proc/play/sound/jack-output.hpp index d793662d3..4aa50f4d2 100644 --- a/src/proc/play/sound/jack-output.hpp +++ b/src/proc/play/sound/jack-output.hpp @@ -21,7 +21,9 @@ */ /** @file jack-output.hpp - ** + ** + ** @todo empty placeholder to underpin the claim: yes we will support Jack Audio! + ** ** @see lumiera::Display ** @see lumiera::DummyPlayer ** @see gui::PlaybackController usage example diff --git a/src/proc/play/timings.cpp b/src/proc/play/timings.cpp index 2f3ab126d..b3b631502 100644 --- a/src/proc/play/timings.cpp +++ b/src/proc/play/timings.cpp @@ -22,7 +22,11 @@ /** @file timings.cpp - ** TODO timings.cpp + ** Implementation of a data tuple for timing specification. + ** A Timings record represents a constraint on playback, and will be + ** used to organise and the calculations necessary to generate the data. + ** Especially, a Timings record serves to establish a relation to an externally + ** fixed time grid or time source. */