Isomet Modular Synthesiser (iMS) API  v1.4.2
iMS API
Classes | Public Types | Public Attributes | List of all members
iMS::SequenceManager Class Reference

#include <include\ImageOps.h>

Collaboration diagram for iMS::SequenceManager:
Collaboration graph
[legend]

Classes

struct  SeqConfiguration
 This struct sets the attributes for the Sequence to use when initiating an Sequence Playback. More...
 

Public Types

using PointClock = ImagePlayer::PointClock
 Defines Internal Oscillator / External Clock operation.
 
using ImageTrigger = ImagePlayer::ImageTrigger
 Defines Image Trigger function.
 
using Polarity = ImagePlayer::Polarity
 Defines polarity of external clock / trigger signals.
 

Public Member Functions

Constructors & Destructor
 SequenceManager (const IMSSystem &)
 Default Constructor. More...
 
 ~SequenceManager ()
 Destructor.
 
Playback Operations
bool StartSequenceQueue (const SeqConfiguration &cfg=SeqConfiguration(), ImageTrigger start_trig=ImageTrigger::CONTINUOUS)
 Begins playback through the sequence queue. More...
 
void SendHostTrigger ()
 Software trigger for sequence Image propagation When either SeqConfiguration::trig or start_trig are set to ImageTrigger::HOST, the application software must send a signal to the hardware to begin playback of either the next Image in the sequence, or the first image in the sequence respectively.
 
Queue Modification
std::uint16_t QueueCount ()
 Number of Sequences programmed into the Queue. More...
 
bool GetSequenceUUID (int index, std::array< std::uint8_t, 16 > &uuid)
 Returns the identity of a particular sequence via its index in the Controller sequence queue. More...
 
bool QueueClear ()
 Remove all sequences from the queue. More...
 
bool RemoveSequence (const ImageSequence &seq)
 Remove an individual sequence from the queue. More...
 
bool RemoveSequence (const std::array< std::uint8_t, 16 > &uuid)
 Remove an individual sequence from the queue. More...
 
bool UpdateTermination (ImageSequence &seq, SequenceTermAction action, int val=0)
 Update the termination behaviour of a specific sequence. More...
 
bool UpdateTermination (const std::array< std::uint8_t, 16 > &uuid, SequenceTermAction action, int val=0)
 Update the termination behaviour of a specific sequence. More...
 

Public Attributes

struct LIBSPEC iMS::SequenceManager::SeqConfiguration cfg
 Defines the configuration for Sequence Playback.
 

Sequence Event Signalling

If the user application requires that new sequences are created and downloaded to the Sequence Queue while playback is operational, it may be advantageous to configure the SequenceManager to inform the application when sequences complete or when the sequence queue has emptied. To do that, create an EventHandler derived class in your code and subscribe it to the SequenceManager using these functions and one of the SequenceEvent messages. The handler will be called at the relevant time which will allow the application to synchronously update the Controller sequence queue with new information.

Warning
Subscribing to sequence events turns on the interrupt sending mechanism in the Controller in order to guarantee minimum latency from the event occurrence. Since this involves sending Controller initiated messages to the SDK, it is inadvisable to subscribe to the SEQUENCE_START event if sequences are expected to be started at a rate greater than approx once every 10msec, as buffer overruns can occur which will lead to the breakdown of communications between the SDK and the iMS System.
void SequenceEventSubscribe (const int message, IEventHandler *handler)
 Subscribe a callback function handler to a given SequenceManager event. More...
 
void SequenceEventUnsubscribe (const int message, const IEventHandler *handler)
 Unsubscribe a callback function handler from a given SequenceManager event. More...
 

Detailed Description

Author
Dave Cowan
Date
2016-05-04
Since
1.2.4

Constructor & Destructor Documentation

iMS::SequenceManager::SequenceManager ( const IMSSystem )

Default Constructor.

Requires a reference to an iMS System in order to carry out communications with the Sequence Queue in the Controller

Member Function Documentation

bool iMS::SequenceManager::GetSequenceUUID ( int  index,
std::array< std::uint8_t, 16 > &  uuid 
)

Returns the identity of a particular sequence via its index in the Controller sequence queue.

Every ImageSequence has a unique ID, which is downloaded to the Controller sequence queue so that, although it is not possible to readback the configuration of every sequence in the queue, it is possible to match the UUID of every sequence with the UUID of an ImageSequence object stored in the application.

Parameters
[in]indexThe offset from the front of the queue from which to retrieve the UUID (0 = Sequence currently playing or next to play if stopped)
[in]uuidA reference to a 16-byte array in which to store the UUID
Returns
True if the operation completed successfully
bool iMS::SequenceManager::QueueClear ( )

Remove all sequences from the queue.

If the sequence queue is currently playing, this function call will fail and return false

Returns
True if the queue was successfully cleared
std::uint16_t iMS::SequenceManager::QueueCount ( )

Number of Sequences programmed into the Queue.

Returns
the number of sequences that are currently in the Controller queue
bool iMS::SequenceManager::RemoveSequence ( const ImageSequence seq)

Remove an individual sequence from the queue.

Removes an ImageSequence from anywhere within the sequence queue. If attempting to remove the sequence from the front of the queue, while it is playing, the operation will still succeed but subsequent behaviour may be undefined. If multiple identical sequences exist in the queue, the sequence most recently added (or most recently played) will be deleted. The function must be called multiple times to remove multiple sequences

Parameters
[in]seqA reference to an ImageSequence object to find in the queue and remove
Returns
True if the removal was carried out successfully
bool iMS::SequenceManager::RemoveSequence ( const std::array< std::uint8_t, 16 > &  uuid)

Remove an individual sequence from the queue.

Removes an ImageSequence from anywhere within the sequence queue. If attempting to remove the sequence from the front of the queue, while it is playing, the operation will still succeed but subsequent behaviour may be undefined. If multiple identical sequences exist in the queue, the sequence most recently added (or most recently played) will be deleted. The function must be called multiple times to remove multiple sequences

Parameters
[in]uuidAn identifier that can be returned from GetSequenceUUID to mark a sequence for deletion
Returns
True if the removal was carried out successfully
void iMS::SequenceManager::SequenceEventSubscribe ( const int  message,
IEventHandler handler 
)

Subscribe a callback function handler to a given SequenceManager event.

SequenceManager can callback user application code when an event occurs in the sequence playback process. Supported events are listed under SequenceEvents. The callback function must inherit from the IEventHandler interface and override its EventAction() method.

Use this member function call to subscribe a callback function to an SequenceManager event. For the period that a callback is subscribed, each time an event in the Controller sequence playback occurs that would trigger the subscribed SequenceManager event, the user function callback will be executed.

Parameters
[in]messageUse the SequenceEvents::Event enum to specify an event to subscribe to
[in]handlerA function pointer to the user callback function to execute on the event trigger.
void iMS::SequenceManager::SequenceEventUnsubscribe ( const int  message,
const IEventHandler handler 
)

Unsubscribe a callback function handler from a given SequenceManager event.

Removes all links to a user callback function from the Event Trigger map so that any events that occur in the Controller sequence playback following the Unsubscribe request will no longer execute that function

Parameters
[in]messageUse the SequenceEvents::Event enum to specify an event to unsubscribe from
[in]handlerA function pointer to the user callback function that will no longer execute on an event
bool iMS::SequenceManager::StartSequenceQueue ( const SeqConfiguration cfg = SeqConfiguration(),
ImageTrigger  start_trig = ImageTrigger::CONTINUOUS 
)

Begins playback through the sequence queue.

The iMS Controller will start playing the ImageSequenceEntry that exists at the front of the Sequence Queue. If the queue is empty, the call will have no effect, but may still return true. Use the QueueCount() function if it is necessary to check for queue contents prior to playback. Image playback will continue through each ImageSequenceEntry and ImageSequence in turn until it either encounters an ImageSequence with a 'STOP_*' termination action or the queue becomes empty.

The queue behaviour may be controlled by the SeqConfiguration struct, which specifies whether the Sequence is clocked by the internal NCO oscillator or an external clock and what method is used to propagate the start of the next ImageSequenceEntry in the list.

The start_trig parameter may be used to control how the Sequence playback begins. If set to CONTINUOUS (or not specified) Sequence playback will start immediately. If set to EXTERNAL, Sequence playback will start when an External trigger is detected. If set to HOST, Sequence playback will begin when a software trigger is sent (Using SendHostTrigger()).

Parameters
[in]cfgThe clocking and trigger configuration for propagating through images in the sequence
[in]start_trigthe type of trigger used to begin the sequence playing back
Returns
true whe the Sequence playback has been initiated
bool iMS::SequenceManager::UpdateTermination ( ImageSequence seq,
SequenceTermAction  action,
int  val = 0 
)

Update the termination behaviour of a specific sequence.

This function is used to change the behaviour of a sequence after it has completed playback. It can be used for example to modify a sequence set to RECYCLE mode so that next time it plays back, it is instead DISCARDed. If multiple identical sequences exist in the queue, the sequence most recently added (or most recently played) will be updated.

Parameters
[in]seqA reference to an ImageSequence object to find in the queue and update
[in]actionThe new action value to program the ImageSequence with
[in]valAn optional Termination value to apply to the sequence
Returns
True if the update was carried out successfully
bool iMS::SequenceManager::UpdateTermination ( const std::array< std::uint8_t, 16 > &  uuid,
SequenceTermAction  action,
int  val = 0 
)

Update the termination behaviour of a specific sequence.

This function is used to change the behaviour of a sequence after it has completed playback. It can be used for example to modify a sequence set to RECYCLE mode so that next time it plays back, it is instead DISCARDed. If multiple identical sequences exist in the queue, the sequence most recently added (or most recently played) will be updated.

Parameters
[in]uuidAn identifier that can be returned from GetSequenceUUID to mark a sequence for update
[in]actionThe new action value to program the ImageSequence with
[in]valAn optional Termination value to apply to the sequence
Returns
True if the update was carried out successfully

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