A Timeline is a list of device parameter values at arbitrary times. More...

#include <Timeline.h>

Inheritance diagram for Lumiverse::ShowControl::Timeline:

Public Member Functions
	Timeline ()
	Creates an empty timeline.

	Timeline (JSONNode data)
	Load a Timeline from JSON data. More...

	Timeline (const Timeline &other)
	Copies a timeline.

void	operator= (const Timeline &other)

virtual	~Timeline ()
	Deletes a timeline.

string	getTimelineKey (Device *d, string paramName)
	Gets the identifier used to refer to a device-parameter keyframe set.

string	getTimelineKey (string id, string paramName)
	Gets the identifier used to refer to a device-parameter keyframe set.

Keyframe	getKeyframe (string identifier, size_t time)
	Gets the keyframe for a given identifier and time. Read-only. More...

map< string, Keyframe >	getKeyframes (Device *d, size_t time)
	Gets the keyframes for a given device and time. Read-only. More...

map< string, map< size_t, Keyframe > > &	getAllKeyframes ()
	Gets the keyframes for the entire timeline.

void	setKeyframe (string identifier, size_t time, LumiverseType *data, bool ucs=false)
	Sets the value for the specified keyframe. More...

void	setKeyframe (Device *d, size_t time, bool ucs=false)
	Sets the value of the keyframes for all parameters of the given device.

void	setKeyframe (Rig *rig, size_t time, bool ucs=false)
	Stores a keyframe from a rig.

void	setKeyframe (DeviceSet devices, size_t time, bool ucs=false)
	Stores a keyframe for a group of selected devices.

void	setKeyframe (string identifier, size_t time, string timelineID, size_t offset=0)
	Stores a nested timeline Keyframe for a particular identifier.

void	setKeyframe (Device *d, size_t time, string timelineID, size_t offset=0)
	Stores a nested timeline Keyframe for a device.

void	setKeyframe (DeviceSet devices, size_t time, string timelineID, size_t offset=0)
	Stores a nested timeline Keyframe for a group of selected devices.

void	deleteKeyframe (string identifier, size_t time)
	Deletes the keyframe with the specified identifier at the specified time.

void	deleteKeyframe (Device *d, size_t time)
	Deletes the keyframes for the specified device at the specified time.

void	deleteKeyframe (DeviceSet devices, size_t time)
	Deletes the keyframes for the specified devices at the specified time.

void	moveKeyframe (string id, size_t oldTime, size_t newTime)
	Moves a keyframe from one time to a different time. If a keyframe already exists at the target time, it is overwritten.

void	deleteKeyframesAfter (string id, size_t start)
	Deletes all keyframes for an id that occur after (>) the start time.

void	deleteKeyframesBetween (size_t start, size_t end)
	Deletes all keyframes between (start < keyframe < end) the specified times.

bool	addEndEvent (string id, shared_ptr< Event > e)
	Adds a new event to the end of the timeline. More...

void	deleteEndEvent (string id)
	Deletes an end event. More...

bool	addEvent (size_t time, shared_ptr< Event > e)
	Adds an Event to the Timeline. More...

void	deleteEvent (size_t time, string id="")
	Deletes Events from the Timeline. More...

vector< shared_ptr< Event > >	getEvents (size_t time, string id="")
	Gets Events at the specified time. More...

shared_ptr< Event >	getEndEvent (string id)
	Gets an end Event. More...

multimap< size_t, shared_ptr< Event > > &	getAllEvents ()
	Returns the multimap containing the Events for this Timeline.

map< string, shared_ptr< Event > > &	getAllEndEvents ()
	Returns the end Events for this Timeline.

virtual shared_ptr< LumiverseType >	getValueAtTime (string id, string paramName, LumiverseType *currentVal, size_t time, map< string, shared_ptr< Timeline > > &tls)
	Returns the value of the specified parameter for the specified device at the specified time. More...

virtual void	executeEvents (size_t prevTime, size_t currentTime)
	Executes the events between the specified times. More...

virtual void	executeEndEvents ()
	Executes all end events in the timeline's list.

virtual int	getLoops ()
	Returns the looping setting for this timeline. More...

virtual void	setLoops (int loops)
	Set the number of loops the timeline should execute. More...

virtual size_t	getLength ()
	Gets the length of the timeline based on stored keyframes. More...

virtual size_t	getLoopLength ()
	Gets the length of the timeline for a single loop. More...

virtual JSONNode	toJSON ()
	Gets the JSON representation of the timeline object.

virtual bool	isDone (size_t time, map< string, shared_ptr< Timeline > > &tls)
	Indicates if the Timeline has no more keyframes after the specified time. More...

virtual void	setCurrentState (map< string, map< string, LumiverseType * > > &state, shared_ptr< Timeline > active, size_t time)
	Takes a state from the layer and updates the keyframes marked with "Use Current State". More...

Keyframe	getPreviousKeyframe (string identifier, size_t time)
	Gets the keyframe closest to happen at or before the given time. More...

virtual size_t	getLoopTime (size_t time)
	Returns the time adjusted for the number of loops the timeline can perfrom.

virtual string	getTimelineTypeName ()
	Used for identifying different kinds of timelines.

Protected Member Functions
void	updateKeyframeState (string id, string paramName, LumiverseType *param, shared_ptr< Timeline > tl, size_t time)
	Updates the Keyframes marked as "Use Current State" in the Timeline's data.

void	loadJSON (JSONNode node)
	Initializes the timeline with the given JSONNode's data.

Protected Attributes
size_t	_length
	Stores the length of the timeline. More...

size_t	_loopLength
	Stores the loop length of the timleine. More...

int	_loops
	Describes how many times the timeline should loop. More...

bool	_lengthIsUpdated
	Indicates if the timeline's length is updated.

bool	_loopLengthIsUpdated
	Indicates if the timeline's loop length is updated.

map< string, map< size_t, Keyframe > >	_timelineData
	Map from unique identifier to timeline keyframes. More...

multimap< size_t, shared_ptr< Event > >	_events
	List of events and times that the events happen.

map< string, shared_ptr< Event > >	_endEvents
	List of events to call at the end. More...

Detailed Description

A Timeline is a list of device parameter values at arbitrary times.

Lumiverse Timelines should be familiar to anyone who's used a timeline based system before. The one difference to highlight specifically is the addition of a new keyframe data type called "Use Current State." When this keyframe value is present, the state of the layer the timeline is being played on will be used as the "current state" whenever this keyframe is encountered. Because of this, this keyframe is typically used only at the beginning of timelines.

Timelines may also loop a specified number of times. Setting the loop parameter to -1 indicates an infinite loop.

In addition to Keyframes, a Timeline may contain Events. Events are arbitrary actions called at the specified times. Events are executed on every loop, or at the very end of the Timeline (after all loops are complete).

Subclasses of timelines are allowed, and encouraged for certain applications. Note that you do not have to override all functions, but probably should at least override getValueAtTime(). Subclasses have access to all the keyframe functions and data structures, but do not have to use them.

Times are specified in ms.

See also: Event

Constructor & Destructor Documentation

Lumiverse::ShowControl::Timeline::Timeline ( JSONNode data )

Load a Timeline from JSON data.

Parameters

data	JSONNode containing a timeline.

Member Function Documentation

bool Lumiverse::ShowControl::Timeline::addEndEvent	(	string	id,
		shared_ptr< Event >	e
	)

Adds a new event to the end of the timeline.

Id is needed for this to allow easy access to end events.

Parameters

id	Identifier for the end event.
e	Event to add

Returns: true on success, false if an event with the given ID alreay exists.

bool Lumiverse::ShowControl::Timeline::addEvent	(	size_t	time,
		shared_ptr< Event >	e
	)

Adds an Event to the Timeline.

Parameters

time	Time to execute the Event
e	Event to add.

void Lumiverse::ShowControl::Timeline::deleteEndEvent ( string id )

Deletes an end event.

Parameters

id	Identifier for the event to delete.

void Lumiverse::ShowControl::Timeline::deleteEvent	(	size_t	time,
		string	id = `""`
	)

Deletes Events from the Timeline.

If an ID is not specified, this function will delete all events at the specified time

Parameters

time	Time to delete the events at
id	Optional identifier for the Event to delete.

void Lumiverse::ShowControl::Timeline::executeEvents	(	size_t	prevTime,
		size_t	currentTime
	)

virtual

Executes the events between the specified times.

Since we don't want Events to execute more than once per play through, we need the previous time to ensure proper execution. This should be maintained by the Layer. Executes events in the range (low, high]

Parameters

prevTime	Last time of update.
currentTime	Current update time

shared_ptr< Event > Lumiverse::ShowControl::Timeline::getEndEvent ( string id )

Gets an end Event.

Parameters

id	Identifier for the desired ID.

Returns: Specified Event if it exists. nullptr if it does not exist.

vector< shared_ptr< Event > > Lumiverse::ShowControl::Timeline::getEvents	(	size_t	time,
		string	id = `""`
	)

Gets Events at the specified time.

If an ID is specified, the vector will contain only the specified Event (if it exists).

Parameters

time	Time to get Events
id	Optional identifier to get a specific Event.

Keyframe Lumiverse::ShowControl::Timeline::getKeyframe	(	string	identifier,
		size_t	time
	)

Gets the keyframe for a given identifier and time. Read-only.

Note that if the keyframe doesn't exist, you will receive an invalid keyframe.

map< string, Keyframe > Lumiverse::ShowControl::Timeline::getKeyframes	(	Device *	d,
		size_t	time
	)

Gets the keyframes for a given device and time. Read-only.

If a keyframe doesn't exist for the parameter, it will be empty.

size_t Lumiverse::ShowControl::Timeline::getLength ( )

virtual

Gets the length of the timeline based on stored keyframes.

/return Length of timeline, max size_t

size_t Lumiverse::ShowControl::Timeline::getLoopLength ( )

virtual

Gets the length of the timeline for a single loop.

This is equal to getLength() for timelines with a loop paramter of 1.

Reimplemented in Lumiverse::ShowControl::SineWave.

int Lumiverse::ShowControl::Timeline::getLoops ( )

virtual

Returns the looping setting for this timeline.

Returns: Number of loops the timeline is set to do.

Keyframe Lumiverse::ShowControl::Timeline::getPreviousKeyframe	(	string	identifier,
		size_t	time
	)

Gets the keyframe closest to happen at or before the given time.

Parameters

identifier	Keyframe identifier
time	Time to get the closest keyframe.

shared_ptr< LumiverseType > Lumiverse::ShowControl::Timeline::getValueAtTime	(	string	id,
		string	paramName,
		LumiverseType *	currentVal,
		size_t	time,
		map< string, shared_ptr< Timeline > > &	tls
	)

virtual

Returns the value of the specified parameter for the specified device at the specified time.

Parameters

id	Device ID
paramName	Parameter name
time	Time in milliseconds to get the value.

Returns: A LumiverseType value for the specified time in the timeline.

Reimplemented in Lumiverse::ShowControl::SineWave.

bool Lumiverse::ShowControl::Timeline::isDone	(	size_t	time,
		map< string, shared_ptr< Timeline > > &	tls
	)

virtual

Indicates if the Timeline has no more keyframes after the specified time.

Note that in the event of nested timelines, this function will recursively call isDone(). For a Timeline to be completely done, every sub-timeline must also be done. In the event of loops, this function might never return true.

Parameters

time	Time to check for done-ness

Returns: true if the Timeline has no keyframes specified after the given time.

void Lumiverse::ShowControl::Timeline::setCurrentState	(	map< string, map< string, LumiverseType * > > &	state,
		shared_ptr< Timeline >	active,
		size_t	time
	)

virtual

Takes a state from the layer and updates the keyframes marked with "Use Current State".

Parameters

state Layer state

Reimplemented in Lumiverse::ShowControl::Cue.

void Lumiverse::ShowControl::Timeline::setKeyframe	(	string	identifier,
		size_t	time,
		LumiverseType *	data,
		bool	ucs = `false`
	)

Sets the value for the specified keyframe.

This function will overwrite existing keyframes without warning.

void Lumiverse::ShowControl::Timeline::setLoops ( int loops )

virtual

Set the number of loops the timeline should execute.

If set to -1, the timeline will loop forever.

Member Data Documentation

map<string, shared_ptr<Event> > Lumiverse::ShowControl::Timeline::_endEvents

protected

List of events to call at the end.

Use this when you know you want something to happen at the end and don't want to continuously update keyframes.

size_t Lumiverse::ShowControl::Timeline::_length

protected

Stores the length of the timeline.

The length is calculated as needed, as it is a potentially time consuming thing to figure out.

size_t Lumiverse::ShowControl::Timeline::_loopLength

protected

Stores the loop length of the timleine.

Calculated as needed and cached.

int Lumiverse::ShowControl::Timeline::_loops

protected

Describes how many times the timeline should loop.

A value of -1 means "loop forever"

map<string, map<size_t, Keyframe> > Lumiverse::ShowControl::Timeline::_timelineData

protected

Map from unique identifier to timeline keyframes.

The unique identifier for device parameter pair is: [deviceID]:[paramName]

The documentation for this class was generated from the following files:

LumiverseShowControl/Timeline.h
LumiverseShowControl/Timeline.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation