Isomet Modular Synthesiser (iMS) API  v1.4.2
iMS API
ImageOps.h
Go to the documentation of this file.
1 /*-----------------------------------------------------------------------------
2 / Title : Image Operations Header
3 / Project : Isomet Modular Synthesiser System
4 /------------------------------------------------------------------------------
5 / File : $URL: http://nutmeg.qytek.lan/svn/sw/trunk/09-Isomet/iMS_SDK/API/ImageOps/h/ImageOps.h $
6 / Author : $Author: dave $
7 / Company : Isomet (UK) Ltd
8 / Created : 2015-04-09
9 / Last update: $Date: 2017-09-11 23:55:34 +0100 (Mon, 11 Sep 2017) $
10 / Platform :
11 / Standard : C++11
12 / Revision : $Rev: 300 $
13 /------------------------------------------------------------------------------
14 / Description:
15 /------------------------------------------------------------------------------
16 / Copyright (c) 2015 Isomet (UK) Ltd. All Rights Reserved.
17 /------------------------------------------------------------------------------
18 / Revisions :
19 / Date Version Author Description
20 / 2015-04-09 1.0 dc Created
21 /
22 /----------------------------------------------------------------------------*/
23 
39 
40 #ifndef IMS_IMAGEOPS_H__
41 #define IMS_IMAGEOPS_H__
42 
43 #include "IMSSystem.h"
44 #include "IEventHandler.h"
45 #include "IBulkTransfer.h"
46 #include "Image.h"
47 
48 #include <memory>
49 #include <thread>
50 
52 #if defined _WIN32 || defined __CYGWIN__
53  #ifdef __GNUC__
54  #define DLL_EXPORT __attribute__ ((dllexport))
55  #define DLL_IMPORT __attribute__ ((dllimport))
56  #else
57  #define DLL_EXPORT __declspec(dllexport) // Note: actually gcc seems to also supports this syntax.
58  #define DLL_IMPORT __declspec(dllimport) // Note: actually gcc seems to also supports this syntax.
59  #endif
60  #define DLL_LOCAL
61 #else
62  #if __GNUC__ >= 4
63  #define DLL_EXPORT __attribute__ ((visibility ("default")))
64  #define DLL_IMPORT __attribute__ ((visibility ("default")))
65  #define DLL_LOCAL __attribute__ ((visibility ("hidden")))
66  #else
67  #define DLL_EXPORT
68  #define DLL_IMPORT
69  #define DLL_LOCAL
70  #endif
71 #endif
72 
73 #if defined(_EXPORTING_IMS)
74  #define LIBSPEC DLL_EXPORT
75  #define LIBLOCAL DLL_LOCAL
76  #define EXPIMP_TEMPLATE
77 #elif defined(_STATIC_IMS)
78  #define LIBSPEC
79  #define LIBLOCAL
80  #define EXPIMP_TEMPLATE
81 #else
82  #define LIBSPEC DLL_IMPORT
83  #define LIBLOCAL DLL_LOCAL
84  #define EXPIMP_TEMPLATE extern
85 #endif
86 
88 // MSVC: Exporting template specialization for use as Post Delay by users
89 // see https://support.microsoft.com/en-us/kb/168958 for explanation
90 EXPIMP_TEMPLATE template class LIBSPEC std::chrono::duration < std::uint16_t, std::ratio<1, 10000> >;
91 
92 
93 namespace iMS
94 {
104  class LIBSPEC ImageDownloadEvents
105  {
106  public:
108  enum Events {
123  Count
124  };
125  };
126 
133  class LIBSPEC ImageDownload : public IBulkTransfer
134  {
135  public:
138 
139  ImageDownload(IMSSystem& ims, const Image& img);
160  ~ImageDownload();
162 
164 
165  bool StartDownload();
166  bool StartVerify();
168 
171 
172  int GetVerifyError();
174 
177 
178  void ImageDownloadEventSubscribe(const int message, IEventHandler* handler);
202  void ImageDownloadEventUnsubscribe(const int message, const IEventHandler* handler);
204  private:
205  // Makes this object non-copyable
206  ImageDownload(const ImageDownload &);
207  const ImageDownload &operator =(const ImageDownload &);
208 
209  class Impl;
210  Impl * p_Impl;
211  };
212 
219  class LIBSPEC ImagePlayerEvents
220  {
221  public:
223  enum Events {
230  Count
231  };
232  };
233 
250  class LIBSPEC ImagePlayer
251  {
252  public:
256  enum class PointClock {
258  INTERNAL,
260  EXTERNAL
261  };
265  enum class ImageTrigger {
267  POST_DELAY,
269  EXTERNAL,
271  HOST,
273  CONTINUOUS
274  };
282  enum class Polarity {
284  NORMAL,
286  INVERSE
287  };
291  enum class StopStyle {
293  GRACEFULLY,
295  IMMEDIATELY
296  };
297 
304  struct LIBSPEC PlayConfiguration
305  {
307  PointClock int_ext{ PointClock::INTERNAL };
309  ImageTrigger trig{ ImageTrigger::CONTINUOUS };
313  int n_rpts{ 0 };
315  Polarity clk_pol{ Polarity::NORMAL };
317  Polarity trig_pol{ Polarity::NORMAL };
318 
320  using post_delay = std::chrono::duration < std::uint16_t, std::ratio<1, 10000> > ;
323  post_delay del{ 0 };
324 
327 
328  PlayConfiguration() {};
333  PlayConfiguration(PointClock c) : int_ext(c) {};
336  PlayConfiguration(PointClock c, ImageTrigger t) : int_ext(c), trig(t) {};
339  PlayConfiguration(PointClock c, std::chrono::duration<int> d) : int_ext(c), trig(ImageTrigger::POST_DELAY), del(std::chrono::duration_cast<post_delay>(d)) {};
342  PlayConfiguration(PointClock c, std::chrono::duration<int> d, Repeats r, int n_rpts) : int_ext(c), trig(ImageTrigger::POST_DELAY), rpts(r), n_rpts(n_rpts), del(std::chrono::duration_cast<post_delay>(d)) {};
345  PlayConfiguration(Repeats r) : rpts(r) {};
348  PlayConfiguration(Repeats r, int n_rpts) : rpts(r), n_rpts(n_rpts) {};
350  } cfg;
352 
355 
356  ImagePlayer(const IMSSystem& ims, const Image& img);
388  ImagePlayer(const IMSSystem& ims, const Image& img, const PlayConfiguration& cfg);
389 
390  ImagePlayer(const IMSSystem& ims, const ImageTableEntry& ite, const kHz InternalClock);
391 
392  ImagePlayer(const IMSSystem& ims, const ImageTableEntry& ite, const int ExtClockDivide);
393 
394  ImagePlayer(const IMSSystem& ims, const ImageTableEntry& ite, const PlayConfiguration& cfg, const kHz InternalClock);
395 
396  ImagePlayer(const IMSSystem& ims, const ImageTableEntry& ite, const PlayConfiguration& cfg, const int ExtClockDivide);
399  ~ImagePlayer();
401 
404 
405  bool Play(ImageTrigger start_trig = ImageTrigger::CONTINUOUS);
428  bool GetProgress();
442  bool Stop(StopStyle stop);
447  inline bool Stop() { return this->Stop(StopStyle::GRACEFULLY); };
449 
452 
453  void SetPostDelay(const std::chrono::duration<double>& dly);
460 
463 
464  void ImagePlayerEventSubscribe(const int message, IEventHandler* handler);
488  void ImagePlayerEventUnsubscribe(const int message, const IEventHandler* handler);
490 
491  private:
492  // Make this object non-copyable
493  ImagePlayer(const ImagePlayer &);
494  const ImagePlayer &operator =(const ImagePlayer &);
495 
496  class Impl;
497  Impl * p_Impl;
498  };
499 
506  class LIBSPEC ImageTableViewer
507  {
508  public:
511 
512  ImageTableViewer(const IMSSystem& ims) : myiMS(ims) {};
526 
528 
529  const int Entries() const;
533 
535  const ImageTableEntry operator[](const std::size_t idx) const;
550 
564  friend LIBSPEC std::ostream& operator<< (std::ostream& stream, const ImageTableViewer&);
565  private:
566  // Make this object non-copyable
567  ImageTableViewer(const ImageTableViewer& other);
568  ImageTableViewer& operator= (const ImageTableViewer& other);
569 
570  const IMSSystem& myiMS;
571  };
572 
579  class LIBSPEC SequenceDownload
580  {
581  public:
584 
585  SequenceDownload(IMSSystem& ims, const ImageSequence& seq);
605  ~SequenceDownload();
607 
609 
610  bool Download();
617 
618  private:
619  // Makes this object non-copyable
621  const SequenceDownload &operator =(const SequenceDownload &);
622 
623  class Impl;
624  Impl * p_Impl;
625  };
626 
636  class LIBSPEC SequenceEvents
637  {
638  public:
640  enum Events {
647  Count
648  };
649  };
650 
651 
660  class LIBSPEC SequenceManager
661  {
662  public:
664 
665  SequenceManager(const IMSSystem&);
670  ~SequenceManager();
672 
679 
685  struct LIBSPEC SeqConfiguration
686  {
688  PointClock int_ext{PointClock::INTERNAL };
690  ImageTrigger trig{ ImageTrigger::CONTINUOUS };
692  Polarity clk_pol{ Polarity::NORMAL };
694  Polarity trig_pol{ Polarity::NORMAL };
695 
698 
699  SeqConfiguration() {};
704  SeqConfiguration(PointClock c) : int_ext(c) {};
707  SeqConfiguration(PointClock c, ImageTrigger t) : int_ext(c), trig(t) {};
709  } cfg;
711 
713 
714  bool StartSequenceQueue(const SeqConfiguration& cfg = SeqConfiguration(), ImageTrigger start_trig = ImageTrigger::CONTINUOUS);
737  void SendHostTrigger();
739 
741 
742  std::uint16_t QueueCount();
753  bool GetSequenceUUID(int index, std::array<std::uint8_t, 16>& uuid);
758  bool QueueClear();
768  bool RemoveSequence(const ImageSequence& seq);
778  bool RemoveSequence(const std::array<std::uint8_t, 16>& uuid);
789  bool UpdateTermination(ImageSequence& seq, SequenceTermAction action, int val = 0);
800  bool UpdateTermination(const std::array<std::uint8_t, 16>& uuid, SequenceTermAction action, int val = 0);
802 
817 
818  void SequenceEventSubscribe(const int message, IEventHandler* handler);
840  void SequenceEventUnsubscribe(const int message, const IEventHandler* handler);
841  private:
842  // Makes this object non-copyable
844  const SequenceManager &operator =(const SequenceManager &);
845 
846  class Impl;
847  Impl * p_Impl;
848  };
849 }
850 
851 #undef EXPIMP_TEMPLATE
852 #undef LIBSPEC
853 #endif
Events
List of Events raised by the Image Player.
Definition: ImageOps.h:223
Events
List of Events raised by the Image Downloader.
Definition: ImageOps.h:640
Once an Image has been downloaded to Controller memory, ImagePlayer can be used to configure and begi...
Definition: ImageOps.h:250
Event raised on completion of a download verify, if the download failed. param contains the number of...
Definition: ImageOps.h:116
Provides a mechanism for downloading and verifying Images to a Controller's memory.
Definition: ImageOps.h:133
PlayConfiguration(PointClock c)
Constructor with Clock Initialisation. Use this to set the Clock to be supplied from an External sign...
Definition: ImageOps.h:333
Event raised when an Image in the Controller begins playback.
Definition: ImageOps.h:227
SeqConfiguration(PointClock c)
Constructor with Clock Initialisation. Use this to set the Clock to be supplied from an External sign...
Definition: ImageOps.h:704
A sequence of ImagePoints played out sequentially by the Controller and driven by the Synthesiser...
Definition: Image.h:228
Event raise when unable to begin a fast transfer of image data to memory, e.g. Image memory is full...
Definition: ImageOps.h:118
Events
List of Events raised by the Image Downloader.
Definition: ImageOps.h:108
std::chrono::duration< std::uint16_t, std::ratio< 1, 10000 > > post_delay
This type is used internally to define the correct scaling between std::chrono classes and the hardwa...
Definition: ImageOps.h:320
Interface Specification class for sending large binary data objects to the iMS.
Definition: IBulkTransfer.h:102
Event raise when unable to transfer any data through DMA mechanism.
Definition: ImageOps.h:120
STL namespace.
Interface Class for User Application code to receive and process events from the iMS library...
PlayConfiguration(PointClock c, std::chrono::duration< int > d, Repeats r, int n_rpts)
Constructor with Clock Initialisation, Post-Delay and Image Repeats. Use this to configure the Clock ...
Definition: ImageOps.h:342
Event raised when an error occurs in processing the sequence queue (typically if the sequence queue w...
Definition: ImageOps.h:646
ImageRepeats
Each Image can be repeated, either a programmable number of times, or indefinitely.
Definition: Image.h:665
An ImageSequence object completely defines a sequence to be played back on an iMS Controller in terms...
Definition: Image.h:857
PlayConfiguration(PointClock c, ImageTrigger t)
Constructor with Clock & Trigger Initialisation. Use this to set the Clock, Trigger or both to be sup...
Definition: ImageOps.h:336
An object representing the overall configuration of an attached iMS System and permits applications t...
Definition: IMSSystem.h:361
This struct sets the attributes for the ImagePlayer to use when initiating an Image Playback...
Definition: ImageOps.h:304
Event raised at the beginning of playback of each sequence.
Definition: ImageOps.h:642
PlayConfiguration(PointClock c, std::chrono::duration< int > d)
Constructor with Clock Initialisation and Post-Delay. Use this for a configurable delay between image...
Definition: ImageOps.h:339
SequenceTermAction
Operation to perform on the completion of the last repeat of the last entry in a Sequence.
Definition: Image.h:823
bool Stop()
Halts the Image Playback After Last Point in Image or Repeat.
Definition: ImageOps.h:447
Provides a mechanism for viewing the ImageTable associated with an iMS System.
Definition: ImageOps.h:506
ImageTrigger
At the end of each Image, the next Image in the sequence (or the next Repeat of the same image) will ...
Definition: ImageOps.h:265
Event raised after the final image of a sequence has completed and there are no more sequences in the...
Definition: ImageOps.h:644
The entire API is encapsulated by the iMS namespace.
Definition: Auxiliary.h:95
Event raised in response to ImagePlayer::GetProgress(). Indicates the number of points into an Image ...
Definition: ImageOps.h:225
Classes for storing sequences of synchronous multi-channel RF drive data.
Classes within this group are used to store information about an iMS System and to Connect / Disconne...
PlayConfiguration(Repeats r, int n_rpts)
Constructor with Programmable Repeats. Use this to set the Image to Repeat a programmable number of t...
Definition: ImageOps.h:348
Polarity
The external signal connections can be configured to be active on the rising edge or the falling edge...
Definition: ImageOps.h:282
SeqConfiguration(PointClock c, ImageTrigger t)
Constructor with Clock & Trigger Initialisation. Use this to set the Clock, Trigger or both to be sup...
Definition: ImageOps.h:707
Event raised when a new download has been accepted prior to memory transfer commencing, reporting the new image index handle.
Definition: ImageOps.h:122
PointClock
Determines whether Image Progression is under the control of an internal or external clock...
Definition: ImageOps.h:256
Event raised when an Image in the Controller completes playback.
Definition: ImageOps.h:229
Interface Class for an Event Handler to be defined in User Code and subscribed to library events...
Definition: IEventHandler.h:146
Event raised when ImageDownload has confirmed that the iMS Controller received all of the Image data...
Definition: ImageOps.h:110
PlayConfiguration(Repeats r)
Constructor with Indefinite Repeats. Use this to set the Image to Repeat Always until Stopped by User...
Definition: ImageOps.h:345
StopStyle
The ImagePlayer can end the Image Playback either at the end of the Image or Repeat, or immediately.
Definition: ImageOps.h:291
Interface Specification class for sending large binary data objects to the iMS.
Event raised on completion of a download verify, if the download was successfully verified...
Definition: ImageOps.h:114
All the different types of events that can be triggered by the SequenceManager class.
Definition: ImageOps.h:636
The Image is played back only once.
All the different types of events that can be triggered by the ImagePlayer class. ...
Definition: ImageOps.h:219
Type Definition for all operations that require a frequency specification in kiloHertz.
Definition: IMSTypeDefs.h:148
All the different types of events that can be triggered by the ImageDownload class.
Definition: ImageOps.h:104
Event raised each time the ImageDownload class registers an error in the download process...
Definition: ImageOps.h:112
Definition: ImageOps.h:660
An ImageTableEntry is created by the SDK on connecting to an iMS System, one for each Image that is s...
Definition: Image.h:579
This struct sets the attributes for the Sequence to use when initiating an Sequence Playback...
Definition: ImageOps.h:685
This class is a worker for transmitting an ImageSequence to an iMS Controller and joining it to the b...
Definition: ImageOps.h:579