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

Once an Image has been downloaded to Controller memory, ImagePlayer can be used to configure and begin playback. More...

#include <include\ImageOps.h>

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

Classes

struct  PlayConfiguration
 This struct sets the attributes for the ImagePlayer to use when initiating an Image Playback. More...
 

Public Types

enum  PointClock { PointClock::INTERNAL, PointClock::EXTERNAL }
 Determines whether Image Progression is under the control of an internal or external clock. More...
 
enum  ImageTrigger { ImageTrigger::POST_DELAY, ImageTrigger::EXTERNAL, ImageTrigger::HOST, ImageTrigger::CONTINUOUS }
 At the end of each Image, the next Image in the sequence (or the next Repeat of the same image) will begin after the ImageTrigger condition is satisfied. More...
 
enum  Polarity { Polarity::NORMAL, Polarity::INVERSE }
 The external signal connections can be configured to be active on the rising edge or the falling edge (CLK, TRIG), high or low (ENABLE) More...
 
enum  StopStyle { StopStyle::GRACEFULLY, StopStyle::IMMEDIATELY }
 The ImagePlayer can end the Image Playback either at the end of the Image or Repeat, or immediately. More...
 
using Repeats = ImageRepeats
 Each Image can be repeated, either a programmable number of times, or indefinitely. More...
 

Public Member Functions

Constructor & Destructor
 ImagePlayer (const IMSSystem &ims, const Image &img)
 Constructor for ImagePlayer Object. More...
 
 ImagePlayer (const IMSSystem &ims, const Image &img, const PlayConfiguration &cfg)
 Constructor for ImagePlayer Object with User Configuration. More...
 
 ImagePlayer (const IMSSystem &ims, const ImageTableEntry &ite, const kHz InternalClock)
 
 ImagePlayer (const IMSSystem &ims, const ImageTableEntry &ite, const int ExtClockDivide)
 
 ImagePlayer (const IMSSystem &ims, const ImageTableEntry &ite, const PlayConfiguration &cfg, const kHz InternalClock)
 
 ImagePlayer (const IMSSystem &ims, const ImageTableEntry &ite, const PlayConfiguration &cfg, const int ExtClockDivide)
 
 ~ImagePlayer ()
 Destructor for ImagePlayer Object.
 
Play Control Functions
bool Play (ImageTrigger start_trig=ImageTrigger::CONTINUOUS)
 Starts Image Playback. More...
 
bool GetProgress ()
 Requests current Point Progress. More...
 
bool Stop (StopStyle stop)
 Halts the Image Playback. More...
 
bool Stop ()
 Halts the Image Playback After Last Point in Image or Repeat. More...
 
Post Delay helper function
void SetPostDelay (const std::chrono::duration< double > &dly)
 Helper function that sets the Post Delay configuration attribute from any compatible std::chrono class (e.g. std::chrono::milliseconds(100.0)) More...
 
Event Notifications
void ImagePlayerEventSubscribe (const int message, IEventHandler *handler)
 Subscribe a callback function handler to a given ImagePlayerEvent. More...
 
void ImagePlayerEventUnsubscribe (const int message, const IEventHandler *handler)
 Unsubscribe a callback function handler from a given ImageDownloadEvent. More...
 

Public Attributes

struct LIBSPEC iMS::ImagePlayer::PlayConfiguration cfg
 Defines the configuration for Image Playback.
 

Detailed Description

Once an Image has been downloaded to Controller memory, ImagePlayer can be used to configure and begin playback.

ImagePlayer contains a Configuration Structure which holds all of the different attributes that may be used to modify the behaviour of the playback, including internal oscillator or external clock, next-image triggering and image repeating. It does not define the internal oscillator clock rate for ImagePoint playback frequency when not using an external clock; this information is stored in the Image class.

Once constructed, the ImagePlayer.Play() function will begin playback, ImagePlayer.Stop() will end playback (immediately or at the end of an image) and ImagePlayer.GetProgress() will raise an event to the user application indicating the current ImagePoint that has been reached in playback.

Author
Dave Cowan
Date
2015-11-11
Since
1.0

Member Typedef Documentation

Each Image can be repeated, either a programmable number of times, or indefinitely.

Repeats

Since
1.0

Member Enumeration Documentation

At the end of each Image, the next Image in the sequence (or the next Repeat of the same image) will begin after the ImageTrigger condition is satisfied.

Since
1.0
Enumerator
POST_DELAY 

A programmable timer is started at the end of the image. The next image is triggered after the timer times out.

EXTERNAL 

The next image is triggered when an edge is detected on the TRIG signal connected to the Controller.

HOST 

The next image is triggered when application software sends a 'User Trigger' request.

CONTINUOUS 

The next image is triggered immediately.

Determines whether Image Progression is under the control of an internal or external clock.

Since
1.0
Enumerator
INTERNAL 

ImagePoint progression through the Image at a rate determined by the programming of the internal NCO (Numerically Controlled Oscillator)

EXTERNAL 

ImagePoint progression through the Image one point per edge detected on the CLK signal connected to the Controller.

The external signal connections can be configured to be active on the rising edge or the falling edge (CLK, TRIG), high or low (ENABLE)

Since
1.0
Enumerator
NORMAL 

CLK / TRIG are active on the rising edge. ENABLE is active high.

INVERSE 

CLK / TRIG are active on the falling edge. ENABLE is active low.

The ImagePlayer can end the Image Playback either at the end of the Image or Repeat, or immediately.

Since
1.0
Enumerator
GRACEFULLY 

The default method for stopping the Image is to action the Stop request at the end of the current Image, or Image Repeat.

IMMEDIATELY 

Use this to end the Image Playback as soon as the command is processed by the Controller.

Constructor & Destructor Documentation

iMS::ImagePlayer::ImagePlayer ( const IMSSystem ims,
const Image img 
)

Constructor for ImagePlayer Object.

An IMSSystem object, representing the configuration of an iMS target on which an Image has already been downloaded, must be passed by const reference to the ImagePlayer constructor.

The IMSSystem object must exist before the ImagePlayer object, and must remain valid (not destroyed) until the ImagePlayer object itself is destroyed.

The Image to be played back must also be passed by reference. ImagePlayer will check the unique ID (UUID) of an Image against the value that is in memory on the hardware to ensure that it is playing the same Image that has been downloaded.

Once constructed, the object can neither be copied or assigned to another instance.

Parameters
[in]imsA const reference to the iMS System which is the target on which to playback the Image
[in]imgA const reference to the Image that has been downloaded to the target
Since
1.0
iMS::ImagePlayer::ImagePlayer ( const IMSSystem ims,
const Image img,
const PlayConfiguration cfg 
)

Constructor for ImagePlayer Object with User Configuration.

As per the default constructor, but also receives a const reference to a PlayConfiguration struct which will have already been modified by the application to change the playback behaviour. The attributes of the struct are copied to the internal configuration struct.

An alternative is to use the default constructor and modify the configuration manually after construction.

Parameters
[in]imsA const reference to the iMS System which is the target for downloading the Image
[in]imgA const reference to the Image that has been downloaded to the target
[in]cfgA const reference to a PlayConfiguration playback configuration structure
Since
1.0

Member Function Documentation

bool iMS::ImagePlayer::GetProgress ( )

Requests current Point Progress.

This function call will request from the Controller the current ImagePoint position within the playback of the current Image. If an Image playback is not in progress, this function call will return false.

Once the Controller has responded with the ImagePoint position, an ImagePlayerEvent::POINT_PROGRESS event will be triggered containing the point position which the application can register to receive.

Returns
true if the Progress request was successfully sent to the Controller
Since
1.0
void iMS::ImagePlayer::ImagePlayerEventSubscribe ( const int  message,
IEventHandler handler 
)

Subscribe a callback function handler to a given ImagePlayerEvent.

ImagePlayer can callback user application code when an event occurs during playback. Supported events are listed under ImagePlayerEvents. 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 ImagePlayerEvent. For the period that a callback is subscribed, each time an event in ImagePlayer occurs that would trigger the subscribed ImagePlayerEvent, the user function callback will be executed.

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

Unsubscribe a callback function handler from a given ImageDownloadEvent.

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

Parameters
[in]messageUse the ImageDownloadEvents::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
Since
1.0
bool iMS::ImagePlayer::Play ( ImageTrigger  start_trig = ImageTrigger::CONTINUOUS)

Starts Image Playback.

This function will begin the playback of an Image resident in Controller memory immediately on receipt of the message by the Controller. If an Image is already playing, the function call will fail and return false. Likewise, if an Image Download is in progress, the function call will fail and return false. If no Image has been downloaded to the Controller, this function will run successfully, but nothing will happen on the Controller.

Once the Controller has responded indicating that the Image Playback has started, an ImagePlayerEvent::IMAGE_STARTED event will be raised which the application can register to receive

Returns
true if the Play Image request was sent to the Controller successfully.
Since
1.0
void iMS::ImagePlayer::SetPostDelay ( const std::chrono::duration< double > &  dly)

Helper function that sets the Post Delay configuration attribute from any compatible std::chrono class (e.g. std::chrono::milliseconds(100.0))

Parameters
[in]dlyUse one of the derived std::chrono classes to set an appropriate post-image delay
Since
1.0
bool iMS::ImagePlayer::Stop ( StopStyle  stop)

Halts the Image Playback.

This function call will end the playback of an Image that is currently taking place on the Controller. There are two methods for stopping Image playback: (1) StopStyle::GRACEFULLY : Ends the Image playback after the last point of the current Image. If the Image is being repeated, either indefinitely or programmatically, playback will halt at the last point of the current Repeat, irrespective of whether there are more repeats programmed to happen. (2) StopStyle::IMMEDIATELY : Ends the Image playback as soon as the message is received by the Controller.

Parameters
[in]stopDefines which Image Stop method to use
Returns
true if the Stop message was successfully sent to the Controller.
Since
1.0
bool iMS::ImagePlayer::Stop ( )
inline

Halts the Image Playback After Last Point in Image or Repeat.

Default Stop function. Identical to Stop(StopStyle::GRACEFULLY);

Since
1.0

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