placement.hpp File Reference

Go to the source code of this file.

Description

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.

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 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, 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 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 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 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<Clip> 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 acceptable).

See also

ExplicitPlacement

LocatingPin interface for controlling the positioning parameters

Definition in file placement.hpp.

#include "lib/error.hpp"
#include "lib/hash-indexed.hpp"
#include "lib/time/timevalue.hpp"
#include "steam/mobject/session/locatingpin.hpp"
#include "steam/asset/pipe.hpp"
#include <memory>

Classes
class	Placement< MO, B >
	A refcounting Handle to an MObject of type MO, used to constrain or explicitly specify the location where the MObject is supposed to be within the Session/Model. More...
class	Placement< MO, B >
	A refcounting Handle to an MObject of type MO, used to constrain or explicitly specify the location where the MObject is supposed to be within the Session/Model. More...
class	Placement< MObject, MObject >
	this specialisation forms the root of all placements and defines all of Placement's actual functionality. More...

Typedefs
typedef Placement< MObject >	PlacementMO

Functions
string	format_PlacementID (PlacementMO const &)
bool	isSameDef (PlacementMO const &, PlacementMO const &)
	compare the properties of placement More...

Namespaces
	steam
	Steam-Layer implementation namespace root.
	steam::mobject
	Media-Objects, edit operations and high-level session.
	steam::mobject::session
	Namespace of Session and user visible high-level objects.