placement-ref.hpp File Reference

Go to the source code of this file.

Description

A generic reference mechanism for Placements, as added to the current session.

While this reference itself is not tied to the actual memory layout (it's not a disguised pointer), the implementation relies on the PlacementIndex within the current session for tracking and retrieving the actual Placement implementation object. This approach allows to create active interconnections between placements. We utilise this to create a system of nested scopes within the high-level-model. But for an (external) client, this link to an index implementation is kept transparent and implicit.

PlacementRef is implemented as a smart-handle, based on an hash-ID (LUID), which is also used as key within the Index. This hash-ID is incorporated into the Placement instance too. Each dereferentiation of a placement ref will access the current session to query the index for the corresponding placement instance in memory. This lookup can fail, causing operator*() to throw. Client code may use the bool conversion to verify the validity of an PlacementRef before accessing it – similar to the behaviour of a pointer.

A default created PlacementRef is bottom (and will throw on any access). A valid placement ref can be created from any source leading to a Placement-ID. The expected type of the pointee (MObject) is set by the template parameter used on creation. The validity of this access type is checked, using the RTTI of the pointee (MObject), assuming of course the reference to be valid (resolvable by index). This mechanism allows to pass or re-gain a specifically typed usage context. (e.g. Placement<Effect>)

Note

there is a twist concerning the nominal Placement hierarchy as generated by the return type of PlacementRef::operator*(). While the original Placement (as added to the session) might been defined to mimic a more elaborate hierarchy (e.g. Placement<Fork> inherits from Placement<Meta>), the Placement returned here in these cases will just be a subclass or Placement<MObject> (which in the mentioned example would mean it couldn't be passed to a API function expecting a Placement<Meta>). This is ugly, but doesn't seem to bear any danger.

Todo:

better solution for the ID to type connection ///////////////////////TICKET #523

See also

Placement

PlacementRef_test

Definition in file placement-ref.hpp.

#include "lib/error.hpp"
#include "steam/mobject/placement.hpp"
#include "steam/mobject/explicitplacement.hpp"
#include "steam/mobject/session/session-service-fetch.hpp"

Classes
class	PlacementRef< MX >
	Reference tag denoting a placement attached to the session. More...

Functions
	LUMIERA_ERROR_DECLARE (INVALID_PLACEMENTREF)
	unresolvable placement reference, or of incompatible type
	LUMIERA_ERROR_DECLARE (BOTTOM_PLACEMENTREF)
	NIL placement-ID marker encountered.

Namespaces
	lumiera
	Lumiera public interface.
	steam
	Steam-Layer implementation namespace root.
	steam::mobject
	Media-Objects, edit operations and high-level session.