diff --git a/src/proc/mobject/builderfacade.cpp b/src/proc/mobject/builderfacade.cpp index 5543aa885..3d670f1da 100644 --- a/src/proc/mobject/builderfacade.cpp +++ b/src/proc/mobject/builderfacade.cpp @@ -22,30 +22,33 @@ /** @file builderfacade.cpp - ** TODO builderfacade.cpp + ** Implementation of top-level access to builder functionality */ #include "proc/mobject/builder/common.hpp" #include "proc/mobject/builderfacade.hpp" +#include "proc/mobject/session/fixture.hpp" namespace proc { namespace mobject { - - /** - * Main Operation of the Builder: - * create a render engine for a given part of the timeline - */ - engine::RenderEngine & - BuilderFacade::buildEngine () - { - //////////////////////TODO - } + using session::Fixture; LUMIERA_ERROR_DEFINE (BUILDER_LIFECYCLE, "Builder activated while in non operational state"); + /** + * Main Operation of the Builder: + * rebuild the low-level model based on the current contents of the Session. + */ + Fixture& + BuilderFacade:: rebuildFixture () + { + UNIMPLEMENTED ("build the builder..."); + } + + }} // namespace mobject diff --git a/src/proc/mobject/builderfacade.hpp b/src/proc/mobject/builderfacade.hpp index 22963c6ae..2148e651b 100644 --- a/src/proc/mobject/builderfacade.hpp +++ b/src/proc/mobject/builderfacade.hpp @@ -22,19 +22,28 @@ /** @file builderfacade.hpp - ** TODO builderfacade.hpp + ** Proc-Layer Facade: access to the Builder. + ** The Builder walks the Session model to compile a corresponding render node network. + ** + ** @todo as of 2016 the builder, as the most crucial component within the architecture, + ** still remains to be addressed. While we'd hoped to get ahead faster, it is considered + ** a good idea not to decide upon the implementation based on assumptions. + ** We will start building the builder "when it is ready" */ -#ifndef MOBJECT_BUILDERFACADE_H -#define MOBJECT_BUILDERFACADE_H +#ifndef PROC_MOBJECT_BUILDERFACADE_H +#define PROC_MOBJECT_BUILDERFACADE_H +#include "lib/error.hpp" #include "proc/mobject/builder/common.hpp" -#include "proc/engine/renderengine.hpp" namespace proc { namespace mobject { + namespace session { + class Fixture; + } LUMIERA_ERROR_DECLARE (BUILDER_LIFECYCLE); ///< Builder activated while in non operational state @@ -47,17 +56,10 @@ namespace mobject { class BuilderFacade { public: - /** - * Main Operation of the Builder: - * create a render engine for a given part of the timeline - * @deprecated thats a placeholder! the real invocation is now - * in the course of being worked out ////////////TODO 12/2010 - */ - engine::RenderEngine & buildEngine () ; - // TODO: allocation, GC?????? + session::Fixture & rebuildFixture (); }; }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_BUILDERFACADE_H*/ diff --git a/src/proc/mobject/explicitplacement.hpp b/src/proc/mobject/explicitplacement.hpp index 4628d5889..655a4c6a1 100644 --- a/src/proc/mobject/explicitplacement.hpp +++ b/src/proc/mobject/explicitplacement.hpp @@ -22,12 +22,22 @@ /** @file explicitplacement.hpp - ** TODO explicitplacement.hpp + ** Core abstraction: completely resolved placement of an MObject + ** Within the session model, all media objects are attached with the help + ** of mobject::Placement elements. These are the "glue" to stitch the model + ** together. However, placements are typically only defined in parts, and what + ** is left out in the definition is assumed to be _"obvious from the context"._ + ** + ** The core operation within Proc-Layer is the Builder run, which walks the Session model + ** to resolve and fill in all the contextual information. The result is a completely resolved + ** Placement for each actually visible and relevant entity. Such is represented as ExplicitPlacement. + ** These are arranged into the backbone structure, the Fixture, and the actual render node network + ** necessary to _render_ those contents is attached below. */ -#ifndef MOBJECT_EXPLICITPLACEMENT_H -#define MOBJECT_EXPLICITPLACEMENT_H +#ifndef PROC_MOBJECT_EXPLICITPLACEMENT_H +#define PROC_MOBJECT_EXPLICITPLACEMENT_H #include "proc/mobject/placement.hpp" @@ -90,4 +100,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_EXPLICITPLACEMENT_H*/ diff --git a/src/proc/mobject/interpolator.cpp b/src/proc/mobject/interpolator.cpp deleted file mode 100644 index e0d2d4be3..000000000 --- a/src/proc/mobject/interpolator.cpp +++ /dev/null @@ -1,38 +0,0 @@ -/* - Interpolator - denotes a facility to get (continuously interpolated) parameter values - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -/** @file interpolator.cpp - ** TODO interpolator.cpp - */ - - -#include "proc/mobject/interpolator.hpp" - -namespace proc { -namespace mobject { - - /** */ - - - -}} // namespace proc::mobject diff --git a/src/proc/mobject/interpolator.hpp b/src/proc/mobject/interpolator.hpp index 14c001713..9d59ed8b4 100644 --- a/src/proc/mobject/interpolator.hpp +++ b/src/proc/mobject/interpolator.hpp @@ -22,12 +22,14 @@ /** @file interpolator.hpp - ** TODO interpolator.hpp + ** Core abstraction: automation parameter interpolator + ** Each interpolator implementation has the ability to resolve intermediary + ** values and to provide a parameter value for _every arbitrary point in time._ */ -#ifndef MOBJECT_INTERPOLATOR_H -#define MOBJECT_INTERPOLATOR_H +#ifndef PROC_MOBJECT_INTERPOLATOR_H +#define PROC_MOBJECT_INTERPOLATOR_H @@ -36,7 +38,7 @@ namespace mobject { /** - * Provides the implementation for getting the acutal value + * Provides the implementation for getting the actual value * of a time varying or automated effect/plugin parameter */ template @@ -48,4 +50,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_INTERPOLATOR_H*/ diff --git a/src/proc/mobject/mobject.cpp b/src/proc/mobject/mobject.cpp index b7b18905d..e4f1047d7 100644 --- a/src/proc/mobject/mobject.cpp +++ b/src/proc/mobject/mobject.cpp @@ -22,7 +22,7 @@ /** @file mobject.cpp - ** TODO mobject.cpp + ** Top level implementation functions globally relevant to the session model */ diff --git a/src/proc/mobject/mobject.hpp b/src/proc/mobject/mobject.hpp index 6c68c46c4..214ec19ff 100644 --- a/src/proc/mobject/mobject.hpp +++ b/src/proc/mobject/mobject.hpp @@ -22,12 +22,22 @@ /** @file mobject.hpp - ** TODO mobject.hpp + ** Core abstraction of the Session model: a media object. + ** The contents of the edit and thus of the session are modelled as a collection + ** of MObject entities, each attached by a Placement. Together these form what can + ** be conceived as an _instance_ of the object. The Placement constitutes the relative + ** and contextual information, while the MObject provides the identity and the link + ** to actual media content or plug-in implementations. + ** + ** @todo as of 2016, this core part of the model still needs to be actually implemented. + ** Most of the code in this hierarchy is preliminary or placeholder code, since we + ** prefer to build the system from ground up, not top-down. It is very likely, that + ** MObject will be just a data tuple in the end. */ -#ifndef MOBJECT_MOBJECT_H -#define MOBJECT_MOBJECT_H +#ifndef PROC_MOBJECT_MOBJECT_H +#define PROC_MOBJECT_MOBJECT_H #include "proc/common.hpp" #include "proc/mobject/builder/buildertool.hpp" @@ -113,4 +123,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_MOBJECT_H*/ diff --git a/src/proc/mobject/output-designation.hpp b/src/proc/mobject/output-designation.hpp index 3823c1c13..c9469bdf8 100644 --- a/src/proc/mobject/output-designation.hpp +++ b/src/proc/mobject/output-designation.hpp @@ -22,7 +22,18 @@ /** @file output-designation.hpp - ** TODO output-designation.hpp + ** Core abstraction: symbolic representation of some output target. + ** An OutputDesignation represents something you might want to connect to + ** or towards which you'd like to direct output. It might be _absolute,_ in + ** which case it represents an actual output device attached to the system, + ** or it might be relative, as a placeholder for further wiring and output routing. + ** An example for the latter would be the "master bus". + ** + ** The concept of an OutputDesignation plays a crucial role to allow flexible connection + ** and rearrangement of media content. It allows to build partial structures, which can + ** be connected automatically to a suitable output when placed into the appropriate context. + ** In the end, the Builder will resolve all output designations, finally leading to a fixed + ** set of exit nodes, which can be pulled to deliver content. */ @@ -54,7 +65,7 @@ namespace mobject { * OutputDesignation is always an internal and relative specification * and boils down to referring an asset::Pipe by ID. In order to become * actually effective, some object within the model additionally - * needs to \em claim this pipe-ID, meaning that this object + * needs to _claim_ this pipe-ID, meaning that this object * states to root and represent this pipe. When the builder * encounters a pair of (OutputDesignation, OutputClaim), * an actual stream connection will be wired in the @@ -123,4 +134,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_OUTPUT_DESIGNATION_H*/ diff --git a/src/proc/mobject/parameter.cpp b/src/proc/mobject/parameter.cpp index d13179ec3..25cd61034 100644 --- a/src/proc/mobject/parameter.cpp +++ b/src/proc/mobject/parameter.cpp @@ -22,7 +22,9 @@ /** @file parameter.cpp - ** TODO parameter.cpp + ** Implementation functions of the Parameter abstraction. + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. */ diff --git a/src/proc/mobject/parameter.hpp b/src/proc/mobject/parameter.hpp index 3e22d138a..0782557f0 100644 --- a/src/proc/mobject/parameter.hpp +++ b/src/proc/mobject/parameter.hpp @@ -22,12 +22,14 @@ /** @file parameter.hpp - ** TODO parameter.hpp + ** Core abstraction: parameter to be controlled and possibly automated. + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. */ -#ifndef PROC_MOBJECT_PARAMETER_H -#define PROC_MOBJECT_PARAMETER_H +#ifndef PROC_PROC_MOBJECT_PARAMETER_H +#define PROC_PROC_MOBJECT_PARAMETER_H @@ -57,4 +59,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_PROC_MOBJECT_PARAMETER_H*/ diff --git a/src/proc/mobject/paramprovider.cpp b/src/proc/mobject/paramprovider.cpp index 9571b8e28..617ac4618 100644 --- a/src/proc/mobject/paramprovider.cpp +++ b/src/proc/mobject/paramprovider.cpp @@ -22,7 +22,9 @@ /** @file paramprovider.cpp - ** TODO paramprovider.cpp + ** Implementation functions of the Parameter abstraction. + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. */ diff --git a/src/proc/mobject/paramprovider.hpp b/src/proc/mobject/paramprovider.hpp index 881542ea5..24bdb8ec7 100644 --- a/src/proc/mobject/paramprovider.hpp +++ b/src/proc/mobject/paramprovider.hpp @@ -22,12 +22,14 @@ /** @file paramprovider.hpp - ** TODO paramprovider.hpp + ** Core abstraction: an entity to expose a single parameter + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. */ -#ifndef MOBJECT_PARAMPROVIDER_H -#define MOBJECT_PARAMPROVIDER_H +#ifndef PROC_MOBJECT_PARAMPROVIDER_H +#define PROC_MOBJECT_PARAMPROVIDER_H @@ -57,4 +59,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_PARAMPROVIDER_H*/ diff --git a/src/proc/mobject/placement.cpp b/src/proc/mobject/placement.cpp index 70815632d..200811d36 100644 --- a/src/proc/mobject/placement.cpp +++ b/src/proc/mobject/placement.cpp @@ -22,7 +22,7 @@ /** @file placement.cpp - ** TODO placement.cpp + ** Implementation functions belonging to the Placement entity */ diff --git a/src/proc/mobject/placement.hpp b/src/proc/mobject/placement.hpp index 25812e85c..1f77ad14b 100644 --- a/src/proc/mobject/placement.hpp +++ b/src/proc/mobject/placement.hpp @@ -21,19 +21,22 @@ */ -/** @file placement.hpp - ** Placements are at the very core of all editing operations, - ** because they act as handles to access the media objects to be manipulated. - ** Moreover, Placements are the actual "content" of the Session and Fixture and thus - ** are small handle like objects. Many editing tasks include locating some Placement - ** within the Session or directly take a ref to a Placement. +/** @file placement.hpp + ** Core abstraction: placement of a media object into session context. + ** Placements are at the very core of all editing operations, because they act + ** as handles to access the media objects to be manipulated. + ** Moreover, Placements are the actual "content" stored within the the Session and Fixture + ** data structure and thus are small handle like objects, which can be processed efficiently. + ** Many editing tasks include locating some Placement within the Session or directly take + ** a reference to a Placement. A Placement represents a _specific way to attach content._ + ** They may refer to contextual information and relate themselves to other placements. ** - ** Placements are refcounting smart pointers: By acting on the Placement object, - ** we can change parameters of the way the media object is placed (e.g. adjust an offset), - ** while by dereferencing the Placement object, we access the "real" media object. - ** Usually, any MObject is created by a factory and immediately wrapped into a Placement, + ** On the implementation level, placements are *refcounting smart pointers*: By acting + ** on the Placement object, we can change parameters of the way the media object is placed + ** (e.g. adjust an offset), while by dereferencing the Placement object, we access the media + ** object itself. Usually, any MObject is created by a factory and immediately wrapped into a Placement, ** which takes ownership of the MObject. - ** + ** ** Besides being a handle, Placements define the logical position where some MObject is ** supposed to be located within the Session or Fixture. The way in which this placing happens ** is controlled and parametrised by a collection (chain) of LocatingPin objects. By adding @@ -42,21 +45,21 @@ ** absolute position (time, output). ** ** Together, this yields semantics somewhere in between value semantics and reference semantics. - ** As any smart-ptr, placements are copyable, but each such copy takes on a distinct identity. - ** Moreover, when added to the Session, a placement acts as if it was an \em instance of the object + ** As any smart-ptr, placements are copyable, but each such copy takes on a _distinct identity._ + ** Moreover, when added to the Session, a placement acts as if it was an _instance_ of the object ** it points at, with the purpose to bind this instance into the Session with specific placement - ** properties. Thus, such a placement-within-session \em is an distinguishable entity, because - ** the settings on the contained LocatingPin chain \em do constitute the relation properties + ** properties. Thus, such a placement-within-session _is_ a distinguishable entity, because + ** the settings on the contained LocatingPin chain _do constitute_ the relation properties ** of the MObject "placed" by this placement. To support this rather ref-like semantics, any - ** placement has an embedded ID (identity). Building on this ID, it is possible to create a - ** smart-ptr like PlacementRef to denote a specific placement found within the Session. + ** placement has an embedded ID (identity). Building on this ID, it is possible in turn to + ** create a smart-ptr like PlacementRef to denote a specific placement found within the Session. ** ** Placements are templated on the type of the actual MObject they refer to, so, sometimes ** e.g. we rather use a Placement to be able to use the more specific methods of the - ** session::Clip interface. But please note the following detail: this type - ** labelling and downcasting is the only difference between these subclasses, - ** besides that, they can be replaced literally by one another (slicing is accepted). - ** + ** session::Clip interface. But _please note the following detail:_ this type labelling + ** and downcasting is the _only_ difference between these subclasses, besides that, + ** they can be replaced literally by one another (slicing acceptable). + ** ** @see ExplicitPlacement ** @see LocatingPin interface for controlling the positioning parameters **