Isomet Modular Synthesiser (iMS) API
v1.4.2
iMS API
|
Once an Image has been downloaded to Controller memory, ImagePlayer can be used to configure and begin playback. More...
#include <include\ImageOps.h>
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. | |
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.
Each Image can be repeated, either a programmable number of times, or indefinitely.
Repeats
|
strong |
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.
|
strong |
Determines whether Image Progression is under the control of an internal or external clock.
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. |
|
strong |
|
strong |
The ImagePlayer can end the Image Playback either at the end of the Image or Repeat, or immediately.
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 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.
[in] | ims | A const reference to the iMS System which is the target on which to playback the Image |
[in] | img | A const reference to the Image that has been downloaded to the target |
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.
[in] | ims | A const reference to the iMS System which is the target for downloading the Image |
[in] | img | A const reference to the Image that has been downloaded to the target |
[in] | cfg | A const reference to a PlayConfiguration playback configuration structure |
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.
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.
[in] | message | Use the ImagePlayerEvents::Event enum to specify an event to subscribe to |
[in] | handler | A function pointer to the user callback function to execute on the event trigger. |
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
[in] | message | Use the ImageDownloadEvents::Event enum to specify an event to unsubscribe from |
[in] | handler | A function pointer to the user callback function that will no longer execute on an event |
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
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))
[in] | dly | Use one of the derived std::chrono classes to set an appropriate post-image delay |
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.
[in] | stop | Defines which Image Stop method to use |
|
inline |