diff --git a/src/lib/p.hpp b/src/lib/p.hpp index 0a1deb5fc..5f72fd2b0 100644 --- a/src/lib/p.hpp +++ b/src/lib/p.hpp @@ -1,5 +1,5 @@ /* - P.hpp - customized shared_ptr with ordering and type relationships + P.hpp - customised shared_ptr with ordering and type relationships Copyright (C) Lumiera.org 2008, Hermann Vosseler @@ -21,19 +21,19 @@ */ /** @file p.hpp - ** customized refcounting smart pointer. + ** Customised refcounting smart pointer. ** Template derived from std::tr1::shared_ptr adding total ordering and ** type relationships implemented by forwarding to the pointees. In all other ** respects, it should behave exactly as shared_ptr and is able to cooperate ** and share ownership with other shared_ptr instantiations. ** ** By default different instantiations of shared_ptr are completely unrelated types, - ** even if using inherintance related type parameters for instantiation: a shared_ptr + ** even if using inheritance related type parameters for instantiation: a shared_ptr ** isn't some kind-of shared_ptr -- we need to do an explicit static_ptr_cast. Another ** common problem is the definition of equality and ordering relations for shared_ptr: ** equality is based on the equality of the managed pointers, while ordering is built upon ** the ref count. While generally this may be a good compromise, in our case it hinders treating - ** the smart ptrs within the application almost as if they were the objects themselfs and proved + ** the smart ptrs within the application almost as if they were the objects themselves and proved ** an obstacle for writing generic helper functions. ** ** the P template resolves these problems by implementing the ordering operators in terms of diff --git a/src/proc/mobject/placement-index.hpp b/src/proc/mobject/placement-index.hpp new file mode 100644 index 000000000..2df8be57e --- /dev/null +++ b/src/proc/mobject/placement-index.hpp @@ -0,0 +1,62 @@ +/* + PLACEMENT-INDEX.hpp - tracking individual Placements and their relations + + Copyright (C) Lumiera.org + 2009, 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 placement-ref.hpp + ** + ** @see Placement + ** @see PlacementRef_test + ** + */ + + + +#ifndef MOBJECT_PLACEMENT__REF_H +#define MOBJECT_PLACEMENT__REF_H + +//#include "pre.hpp" +//#include "proc/mobject/session/locatingpin.hpp" +//#include "proc/asset/pipe.hpp" + +//#include + + +namespace mobject { + +// using std::tr1::shared_ptr; + + + + /** + */ + class PlacementRef + { + }; + + + + + + + +} // namespace mobject +#endif diff --git a/src/proc/mobject/placement-ref.hpp b/src/proc/mobject/placement-ref.hpp new file mode 100644 index 000000000..7e04514d7 --- /dev/null +++ b/src/proc/mobject/placement-ref.hpp @@ -0,0 +1,62 @@ +/* + PLACEMENT-REF.hpp - generic reference to an individual placement added to the session + + Copyright (C) Lumiera.org + 2009, 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 placement-ref.hpp + ** + ** @see Placement + ** @see PlacementRef_test + ** + */ + + + +#ifndef MOBJECT_PLACEMENT__REF_H +#define MOBJECT_PLACEMENT__REF_H + +//#include "pre.hpp" +//#include "proc/mobject/session/locatingpin.hpp" +//#include "proc/asset/pipe.hpp" + +//#include + + +namespace mobject { + +// using std::tr1::shared_ptr; + + + + /** + */ + class PlacementRef + { + }; + + + + + + + +} // namespace mobject +#endif diff --git a/src/proc/mobject/placement.hpp b/src/proc/mobject/placement.hpp index df71f0d75..a68f3dbce 100644 --- a/src/proc/mobject/placement.hpp +++ b/src/proc/mobject/placement.hpp @@ -36,7 +36,7 @@ ** ** Besides being a handle, Placements define the logical position where some MObject is ** supposed to be located within the EDL or Fixture. The way in which this placing happens - ** is controlled and parametrized by a collection (chain) of LocatingPin objects. By adding + ** is controlled and parametrised by a collection (chain) of LocatingPin objects. By adding ** to this chain, the position of the MObject is increasingly constrained. The simplest ** case of such constraining is to add a FixedLocation, thus placing the MObject at one ** absolute position (time, track). @@ -44,7 +44,7 @@ ** Placements are templated on the type of the actual MObject they refer to, so, sometimes ** 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 - ** labeling and downcasting is the only difference between these subclasses, + ** labelling and downcasting is the only difference between these subclasses, ** besides that, they can be replaced literally by one another (slicing is accepted). ** ** @see ExplicitPlacement @@ -64,14 +64,14 @@ #include -namespace mobject - { +namespace mobject { + namespace session{ class MObjectFactory; } - + class ExplicitPlacement; using std::tr1::shared_ptr; - + /** @@ -88,8 +88,8 @@ namespace mobject typedef lumiera::Time Time; typedef asset::shared_ptr Pipe; - - + + public: /** smart pointer: accessing the MObject, * which is subject to placement. @@ -107,7 +107,7 @@ namespace mobject virtual ~Placement() {}; - + /** interface for defining the kind of placement * to employ, and for controling any additional diff --git a/tests/43session.tests b/tests/43session.tests index 887cbdf4c..b72392b8b 100644 --- a/tests/43session.tests +++ b/tests/43session.tests @@ -29,6 +29,14 @@ PLANNED "PlacementBasic_test" PlacementBasic_test < + + 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. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +//#include "proc/asset/media.hpp" +//#include "proc/mobject/session.hpp" +//#include "proc/mobject/session/edl.hpp" +//#include "proc/mobject/session/testclip.hpp" +#include "proc/mobject/placement.hpp" +//#include "proc/mobject/explicitplacement.hpp" +//#include "lib/util.hpp" + +//#include +//#include + +//using boost::format; +//using lumiera::Time; +//using util::contains; +using std::string; +//using std::cout; + + +namespace mobject { +namespace session { +namespace test { + + using asset::VIDEO; + + + + /*************************************************************************** + * @test basic behaviour of the index mechanism used to keep track of + * individual Placements as added to the current Session.. + * @see mobject::Placement + * @see mobject::MObject#create + * @see mobject::Placement#addPlacement + * @see mobject::Placement#resolve + */ + class PlacementIndex_test : public Test + { + typedef shared_ptr PM; + typedef shared_ptr PCA; + + virtual void + run (Arg) + { + /////////////////////////////////TODO + } + }; + + + /** Register this test class... */ + LAUNCHER (PlacementIndex_test, "unit session"); + + +}}} // namespace mobject::session::test diff --git a/tests/components/proc/mobject/placement-ref-test.cpp b/tests/components/proc/mobject/placement-ref-test.cpp new file mode 100644 index 000000000..20e38cede --- /dev/null +++ b/tests/components/proc/mobject/placement-ref-test.cpp @@ -0,0 +1,75 @@ +/* + PlacementRef(Test) - generic reference to a Placement within the Session + + Copyright (C) Lumiera.org + 2009, 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. + +* *****************************************************/ + + +#include "lib/test/run.hpp" +//#include "proc/asset/media.hpp" +//#include "proc/mobject/session.hpp" +//#include "proc/mobject/session/edl.hpp" +//#include "proc/mobject/session/testclip.hpp" +#include "proc/mobject/placement.hpp" +//#include "proc/mobject/explicitplacement.hpp" +//#include "lib/util.hpp" + +//#include +//#include + +//using boost::format; +//using lumiera::Time; +//using util::contains; +using std::string; +//using std::cout; + + +namespace mobject { +namespace session { +namespace test { + + using asset::VIDEO; + + + + /*************************************************************************** + * @test properties and behaviour of the reference-mechanism for Placements. + * @see mobject::Placement + * @see mobject::MObject#create + * @see mobject::Placement#addPlacement + * @see mobject::Placement#resolve + */ + class PlacementRef_test : public Test + { + typedef shared_ptr PM; + typedef shared_ptr PCA; + + virtual void + run (Arg) + { + /////////////////////////////////TODO + } + }; + + + /** Register this test class... */ + LAUNCHER (PlacementRef_test, "unit session"); + + +}}} // namespace mobject::session::test diff --git a/wiki/renderengine.html b/wiki/renderengine.html index dc449ea39..c99e9b671 100644 --- a/wiki/renderengine.html +++ b/wiki/renderengine.html @@ -1920,10 +1920,17 @@ The general idea is, that each facade interface actually provides access to a sp * {{red{and what else?}}} -
+
''The Problem of referring to an [[MObject]]'' stems from the object //as a concept// encompassing a wider scope then just the current implementation instance. If the object was just a runtime entity in memory, we could use a simple (language) reference or pointer. Actually, this isn't sufficient, as the object reference will pass LayerSeparationInterfaces, will be handed over to code not written in the same implementation language, will be included in an ''UNDO'' record for the UndoManager, and thus will need to be serialized and stored permanently within the SessionStorage.
+Moreover [[MObject instances|MObject]] have a 2-level structure: the core object holds just the properties in a strict sense, i.e. the properties which the object //owns.// Any properties due to putting the object into a specific context, i.e. all relation properties are represented as [[Placement]] of the object. Thus, a reference to a specific ~MObject //instance,// actually denotes a specific Placement of this object into the Session.
 
-{{red{WIP}}}
+!Requirements
+* just the reference allone is sufficient to access the placement //and//&nbsp; the core object.
+* the reference needs to be valid even after internal restructuring in the object store.
+* there must be a way to pass these references through serialisation/deserialisation
+* we need a plain-C representation of the reference, which ideally should be incorporated into the complete implementation
+* references should either be integrated into memory management, or at least it should be possible to detect dangling references
+* it should be possible to make handling of the references completely transparent, if the implementation language supports doing so.
 
 !Two models
 For the implementation of the object references, as linked to the memory management in general, there seem to be the following approaches
@@ -1935,6 +1942,11 @@ For the implementation of the object references, as linked to the memory managem
 
 Obviously, the second approach has quite some appeal &mdash; but, in order to use it, we'd have to mitigate its drawbacks: it bears the danger of creating a second separate code path for C language based clients, presumably receiving lesser care, maintenance and stress testing. The mentioned solution worked out earlier this year for the player mockup (1/2009) tries at least partially to integrate the C functionality, as the actual implementation is derived from the C struct used as handle, thus allowing to use the same pointers for both kinds of interface, and in turn by doing the de-allocation by a call through the C dtor function, which is installed as deleter function with the boost::smart_ptr used as base class of the handle. Conceptually, the interface on this handle is related to the actual implementation refered to by the handle (handle == smart_ptr) as if the latter was a subclass of the former. But on the level of the implementation, there is no inheritance relation between the handle and the referent, and especially this allows to define the handle's interface in terms of abstract interface types usable on the client side, while the referent's interface operates on the types of the service implementation. Thus, the drawback of using a C language interface is turned into the advantage of completely separating implementation and client.
 
+!Implementation concept
+Presumably, none of the both models is usable as-is; rather we try to reconstruct the viable properties of both, starting out with the more elegant second model. Thus, basically the ''reference is a smart-ptr'' referring to the core object. Additionally, it incorporates a ''systematic ID denoting the location of the placement''. This ID without the smart-ptr part is used for the C-implementation, making the full handle implementation a shortcut for an access sequence, which first querries the placement from the Session, followed by dereferencing the placement to get at the core object. Thus, the implementation builds upon another abstraction, the &rarr; PlacementRef, which in turn assumes for an index within the implementation of the [[session datastructure|SessionDataMem]] to track and retrieve the actual Placement.
+
+
+{{red{WIP}}}
@@ -2739,12 +2751,16 @@ there is not much you can do directly with a pipe asset. It is an point of refer Pipes are integrated with the [[management of defaults|DefaultsManagement]]. For example, any pipe uses implicitly some [[processing pattern|ProcPatt]] &mdash; it may default to the empty pattern. This feature enables to apply some standard wiring to the pipes (e.g a fader for audio, similar to the classic mixing consoles). This //is // a global property of the pipe, but &mdash; contrary to the stream type &mdash; this pattern may be switched
-
+
A Placement represents a //relation:// it is always linked to a //Subject// (this being a [[Media Object|MObject]]) and has the meaning to //place// this Subject in some manner, either relatively to other Media Objects, or by some Constraint or simply absolute at (time, output). The latter case is especially important for the build process and thus represented by a special [[Sub-Interface ExplicitPlacement|ExplicitPlacement]]. Besides this simple cases, Placements can also express more specific kinds of "locating" an object, like placing a sound source at a pan position or placing a video clip at a given layer (above or below another video clip)
 
 So basically placements represent a query interface: you can allways ask the placement to find out about the position of the related object in terms of (time, output), and &mdash; depending on the specific object and situation &mdash; also about these additional [[placement derived dimensions|PlacementDerivedDimension]] like sound pan or layer order or similar things which also fit into the general concept of "placing" an object.
 
-The fact of being placed in the [[Session|SessionOverview]]/[[EDL]]is constitutive for all sorts of [[MObject]]s, without Placement they make no sense. Thus &mdash; technically &mdash; Placements act as ''smart pointers''. Of course, there are several kinds of Placements and they are templated on the type of MObject they are refering to. Placements can be //aggregated// to increasingly constrain the resulting "location" of the refered ~MObject. See &rarr; [[handling of Placements|PlacementHandling]] for more details
+The fact of being placed in the [[Session|SessionOverview]]/[[EDL]]is constitutive for all sorts of [[MObject]]s, without Placement they make no sense. Thus &mdash; technically &mdash; Placements act as ''smart pointers''. Of course, there are several kinds of Placements and they are templated on the type of MObject they are refering to. Placements can be //aggregated// to increasingly constrain the resulting "location" of the refered ~MObject. See &rarr; [[handling of Placements|PlacementHandling]] for more details + +!Placements as instance +Effectively, the placement of a given MObject into the Session acts as setting up an concrete instance of this object. This way, placements exhibit a dual nature. When viewed on themselves, like any reference or smart-pointer they behave like values. But, by adding a placement to the session, we again create a unique distinguishable entity with reference semantics: there could be multiple placements of the same object but with varying placement properties. Such a placement-bound-into-the-session is denoted by an generic placement-ID or (as we call it) &rarr; PlacementRef; behind the scenes there is a PlacementIndex keeping track of those "instances" &mdash; allowing us to hand out the PlacementRef (which is just an opaque id) to client code outside the Proc-Layer and generally use it as an shorthand, behaving as if it was an MObject instance + 
For any [[media object|MObject]] within the session, we can allways at least query the time (reference/start) point and the output destination from the [[Placement]], by which the object is being handled. But the simple act of placing an object in some way, can &mdash; depending on the context &mdash; create additional degrees of freedom. To list some important examples:
@@ -2784,6 +2800,16 @@ Placements have //value semantics,// i.e. we don't stress the identity of a plac
+
+
An implementation facility used to keep track of individual Placements and their relations.
+Especially, the [[Session]] maintains such an index, allowing to use the (opaque) PlacementRef tags for referring to a specific "instance" of an MObject, //placed// in a unique way into the current session. And, moreover, this index allows for one placement referring to another placement, so to implement a //relative// placement mode. Because there is an index behind the scenes, it is possible to actually access such a referral in the reverse direction, which is necessary for implementing the desired placement behaviour (if an object instance used as anchor is moved, all objects placed relatively to it have to move accordingly, which necessiates finding those other objects).
+
+
+
+
+
A generic reference mechanism for Placements, as added to the current session.
+While this reference itself is not tied to the actual memory layout (meaning it's //not// a disguised pointer), the implementation relies on a [[placement index facility|PlacementIndex]] for tracking and retrieving the actual Placement implementation object.
+
//This page is a scrapbook for working out the implementation of how to (re)build the [[Fixture]]//
 Structurally, (re)building the Fixture rather belongs to [[Session]]/[[EDLs|EDL]], but it is implemented very similar to the render engine build process: by treating all ~MObjects found in the various ~EDLs with a common [[visiting tool|VisitorUse]], this tool collects a simplified view with everyting made explicit, which can be pulled of as Fixture, i.e. (special kind of) EDL
@@ -3453,9 +3479,11 @@ The Session object is a singleton &mdash; actually it is a »~PImpl«-Facade
 * a collection of ''global Pipes''
 * the ''Fixture'' with a possibility to [[(re)build it|PlanningBuildFixture]]
-
+
The Layout of the Session datastructure in memory is bound by several dependencies: GUI, HighLevelModel, SessionStorage, [[Builder]].
-Currently as of 5/09, this is an ongoing [[implementation and planning effort|PlanningSessionInMem]]
+Currently as of 5/09, this is an ongoing [[implementation and planning effort|PlanningSessionInMem]] + +{{red{TODO...}}} 
{{red{WIP}}}