Isomet Modular Synthesiser (iMS) API  v1.4.2
iMS API
List of all members
iMS::Image Class Reference

A sequence of ImagePoints played out sequentially by the Controller and driven by the Synthesiser. More...

#include <include/Image.h>

Inheritance diagram for iMS::Image:
Inheritance graph
[legend]
Collaboration diagram for iMS::Image:
Collaboration graph
[legend]

Public Member Functions

Constructors & Destructors
 Image (const std::string &name="")
 Empty Constructor. More...
 
 Image (size_t nPts, const ImagePoint &pt, const std::string &name="")
 Fill Constructor. More...
 
 Image (size_t nPts, const ImagePoint &pt, const Frequency &f, const std::string &name="")
 Fill Constructor with Internal Clock Initialisation. More...
 
 Image (size_t nPts, const ImagePoint &pt, const int div, const std::string &name="")
 Fill Constructor with External Clock Divider Initialisation. More...
 
 Image (const_iterator first, const_iterator last, const std::string &name="")
 Range Constructor. More...
 
 Image (const_iterator first, const_iterator last, const Frequency &f, const std::string &name="")
 Range Constructor with Internal Clock Initialisation. More...
 
 Image (const_iterator first, const_iterator last, const int div, const std::string &name="")
 Range Constructor with External Clock Initialisation. More...
 
 Image (const Image &)
 Copy Constructor.
 
Imageoperator= (const Image &)
 Assignment Constructor.
 
 ~Image ()
 Destructor.
 
Insert/Add ImagePoints
void AddPoint (const ImagePoint &pt)
 Add a single new ImagePoint at the end of the Image. More...
 
iterator InsertPoint (iterator it, const ImagePoint &pt)
 Inserts a single new element into the PointList. More...
 
void InsertPoint (iterator it, size_t nPts, const ImagePoint &pt)
 Inserts multiple copies of an element into the PointList. More...
 
void InsertPoint (iterator it, const_iterator first, const_iterator last)
 Inserts a range of ImagePoints into the PointList. More...
 
Remove/Clear ImagePoints
iterator RemovePoint (iterator it)
 Removes a single ImagePoint from the PointList. More...
 
iterator RemovePoint (iterator first, iterator last)
 Removes a range of ImagePoints from the PointList. More...
 
void Clear ()
 Remove all ImagePoints from the Image. More...
 
Image Size
int Size () const
 Returns the number of ImagePoints in the PointList. More...
 
Default Internal Clock Rate
void ClockRate (const Frequency &f)
 Sets the Internal Clock Rate that shall be the default playback frequency for the Image. More...
 
const FrequencyClockRate () const
 Returns the default Internal Clock Rate associated with the Image. More...
 
Default External Clock Divider
void ExtClockDivide (const int div)
 Sets the External Clock Divider ratio. More...
 
const int ExtClockDivide () const
 Returns the default External Clock Divider Ratio associated with the Image. More...
 
- Public Member Functions inherited from iMS::DequeBase< ImagePoint >
void clear ()
 clears the contents More...
 
iterator insert (iterator pos, const ImagePoint &value)
 Inserts a single new element into the DequeBase. More...
 
iterator insert (const_iterator pos, size_t count, const ImagePoint &value)
 Inserts multiple copies of an element into the DequeBase.
 
iterator insert (iterator pos, const_iterator first, const_iterator last)
 Inserts a range of elements into the DequeBase.
 
void push_back (const ImagePoint &value)
 Appends the given element value to the end of the container.
 
void pop_back ()
 Removes the last element of the container.
 
void push_front (const ImagePoint &value)
 Prepends the given element value to the beginning of the container.
 
void pop_front ()
 Removes the first element of the container.
 
iterator erase (iterator pos)
 Removes the element at pos.
 
iterator erase (iterator first, iterator last)
 Removes the elements in the range [first; last].
 
std::size_t size () const
 Returns the number of elements in the container.
 
 DequeBase (const std::string &Name="[no name]", const std::time_t &modified_time=std::time(nullptr))
 Create a default empty List with optional name.
 
 DequeBase (size_t, const ImagePoint &, const std::string &Name="[no name]", const std::time_t &modified_time=std::time(nullptr))
 Fill Constructor.
 
 DequeBase (const_iterator first, const_iterator last, const std::string &Name="[no name]", const std::time_t &modified_time=std::time(nullptr))
 Range Constructor.
 
 DequeBase (const DequeBase &)
 Copy Constructor.
 
 ~DequeBase ()
 Destructor.
 
DequeBaseoperator= (const DequeBase &)
 Assignment Constructor.
 
ImagePointoperator[] (int idx)
 Random Write Access to an element in the Deque. More...
 
const ImagePointoperator[] (int idx) const
 Random Access to an element in the Deque. More...
 
bool operator== (DequeBase const &rhs) const
 Equality Operator checks Deque object UUID's for equivalence. More...
 
const std::array< std::uint8_t, 16 > GetUUID () const
 Returns a vector representing the Unique Identifier assigned to the DequeBase object. More...
 
const std::time_t & ModifiedTime () const
 Returns Time at which the Container was last modified. More...
 
std::string ModifiedTimeFormat () const
 Returns Human-readable string for the time at which the Container was last modified. More...
 
const std::string & Name () const
 A string stored with the Container to aid human users in identifying its purpose. More...
 
std::string & Name ()
 
iterator begin ()
 Returns an iterator pointing to the first element in the DequeBase container. More...
 
const_iterator begin () const
 Returns a const_iterator pointing to the first element in the DequeBase container. More...
 
iterator end ()
 Returns an iterator referring to the past-the-end element in the DequeBase container. More...
 
const_iterator end () const
 Returns a const_iterator referring to the past-the-end element in the DequeBase container. More...
 
const_iterator cbegin () const
 Returns a const_iterator pointing to the first element in the DequeBase container. More...
 
const_iterator cend () const
 Returns a const_iterator referring to the past-the-end element in the DequeBase container. More...
 

Image Description

std::string & Description ()
 A string stored with the Image to aid human users in identifying the purpose of an image. More...
 
const std::string & Description () const
 

Additional Inherited Members

- Public Types inherited from iMS::DequeBase< ImagePoint >
typedef std::deque< ImagePoint >::iterator iterator
 Iterator defined for user manipulation of DequeBase.
 
typedef std::deque< ImagePoint >::const_iterator const_iterator
 Const Iterator defined for user readback of DequeBase.
 

Detailed Description

A sequence of ImagePoints played out sequentially by the Controller and driven by the Synthesiser.

An Image contains a list of ImagePoints and a default Clock Rate. Its length is limited only by the available memory of the Controller onto which it is downloaded.

It can be created, copied, modified, merged and more in software on the host running the SDK, stored to disk inside an ImageProject (from SDK rev1.3) and transferred to/from the iMS Controller using the ImageDownload mechanism.

Once in memory on a Controller, the Image can be played back. This can be triggered by software, or by an external trigger input signal applied to the Controller. At the start of playback, the first ImagePoint is programmed by the Controller into the Synthesiser which updates the RF output of all 4 channels.

The Controller then progresses through the Image sequence ImagePoint by ImagePoint, updating the Synthesiser's RF output as it goes. The Image progression can either propagate using an internal clock or under the control of an external signal applied to the Controller. If using the internal clock, the clock is programmed at the point of downloading the Image with the default value for Clock Rate which is stored alongside the PointList data in the Image object.

If using an Image alongside other Images in an ImageGroup, for Controllers that support it, the internal ClockRate may be overriden by the value programmed into the SequenceTable that is a part of the ImageGroup object.

Author
Dave Cowan
Date
2015-11-03
Since
1.0

Constructor & Destructor Documentation

iMS::Image::Image ( const std::string &  name = "")

Empty Constructor.

Parameters
[in]nameThe optional descriptive name to apply to the image
iMS::Image::Image ( size_t  nPts,
const ImagePoint pt,
const std::string &  name = "" 
)

Fill Constructor.

Use this constructor to generate an Image with nPts number of points, each one initialised to the value of pt

Parameters
[in]nPtsThe size of the Image PointList after construction
[in]ptThe ImagePoint that will fill each of the new elements of the PointList
[in]nameThe optional descriptive name to apply to the image
Since
1.0
iMS::Image::Image ( size_t  nPts,
const ImagePoint pt,
const Frequency f,
const std::string &  name = "" 
)

Fill Constructor with Internal Clock Initialisation.

Use this constructor to generate an Image with nPts number of points, each one initialised to the value of pt and with the Internal default Clock Rate initialised to f

Parameters
[in]nPtsThe size of the Image PointList after construction
[in]ptThe ImagePoint that will fill each of the new elements of the PointList
[in]fThe default Clock Rate that the Image will playback when using the Internal Clock mode
[in]nameThe optional descriptive name to apply to the image
Since
1.0
iMS::Image::Image ( size_t  nPts,
const ImagePoint pt,
const int  div,
const std::string &  name = "" 
)

Fill Constructor with External Clock Divider Initialisation.

Use this constructor to generate an Image with nPts number of points, each one initialised to the value of pt and with the External default Clock Divider Ratio initialised to div

Parameters
[in]nPtsThe size of the Image PointList after construction
[in]ptThe ImagePoint that will fill each of the new elements of the PointList
[in]divThe default Clock Divider Ratio that the Image will apply to the External Clock when using the External Clock mode
[in]nameThe optional descriptive name to apply to the image
Since
1.0
iMS::Image::Image ( const_iterator  first,
const_iterator  last,
const std::string &  name = "" 
)

Range Constructor.

Use this constructor to copy a range of ImagePoints from another Image For example,

// Create an image with 1,024 points initialized to 70MHz, 100%
Image img1 (1024, ImagePoint(FAP(70.0,100.0,0.0)));
// Copy the first 500 points into a second image
Image img2 (img1.begin(), img1.begin()+500);
Parameters
[in]firstAn iterator that points to the first ImagePoint of a range to construct the new Image from
[in]lastAn iterator that points to the element after the last ImagePoint of a range to construct the new Image from
[in]nameThe optional descriptive name to apply to the image
Since
1.0
iMS::Image::Image ( const_iterator  first,
const_iterator  last,
const Frequency f,
const std::string &  name = "" 
)

Range Constructor with Internal Clock Initialisation.

Use this constructor to copy a range of ImagePoints from another Image and set the internal default clock frequency

Parameters
[in]firstAn iterator that points to the first ImagePoint of a range to construct the new Image from
[in]lastAn iterator that points to the element after the last ImagePoint of a range to construct the new Image from
[in]fThe default Clock Rate that the Image will playback when using the Internal Clock mode
[in]nameThe optional descriptive name to apply to the image
Since
1.0
iMS::Image::Image ( const_iterator  first,
const_iterator  last,
const int  div,
const std::string &  name = "" 
)

Range Constructor with External Clock Initialisation.

Use this constructor to copy a range of ImagePoints from another Image and set the external default clock divider ratio

Parameters
[in]firstAn iterator that points to the first ImagePoint of a range to construct the new Image from
[in]lastAn iterator that points to the element after the last ImagePoint of a range to construct the new Image from
[in]divThe default Clock Divider Ratio that the Image will apply to the external clock signal when using the External Clock mode
[in]nameThe optional descriptive name to apply to the image
Since
1.0

Member Function Documentation

void iMS::Image::AddPoint ( const ImagePoint pt)

Add a single new ImagePoint at the end of the Image.

Extends the length of the Image by one ImagePoint and copies to it the data supplied in the const reference pt

Equivalent to

img.InsertPoint(img.end(), 1, pt);
Parameters
[in]ptThe ImagePoint to append to the end of the Image
Since
1.0
void iMS::Image::Clear ( )

Remove all ImagePoints from the Image.

The PointList is cleared, all ImagePoints are removed from it and destroyed. The new size of the Image will be zero and Image::begin() == Image::end()

Since
1.0
void iMS::Image::ClockRate ( const Frequency f)

Sets the Internal Clock Rate that shall be the default playback frequency for the Image.

An Image shall have associated with it a default Clock Rate. This is the frequency at which the iMS Controller playback will propagate from one ImagePoint to the next when it is operated in Internal Clock Mode (see ImagePlayer::PointClock).

If the Controller supports multiple images and playback from ImageGroup's, the ImageGroup will contain a sequence table and in that case, the Clock Rate for playing back the Image as part of a sequence may be overriden by the Clock Rate field specified in the Sequence Table.

Parameters
[in]fA Frequency variable to set the Image default internal Clock Rate from.
Since
1.0
const Frequency& iMS::Image::ClockRate ( ) const

Returns the default Internal Clock Rate associated with the Image.

The Image contains a default Clock Rate which shall be used as the frequency for playing out an Image when the Controller is configured for Internal Clock mode and is not overriden by the Clock Rate specified in a sequence table.

Returns
A Frequency value that is the default Internal Clock Rate associated with an Image
Since
1.0
std::string& iMS::Image::Description ( )

A string stored with the Image to aid human users in identifying the purpose of an image.

A descriptive string can be set alongside the Image to allow users to identify and differentiate between images without having to browse through the point data. The description is optional, and if, not used, the description will simply default to "image".

Updating the Image Description does not cause the Image UUID to change.

void iMS::Image::ExtClockDivide ( const int  div)

Sets the External Clock Divider ratio.

An Image shall have associated with it a default external Clock Divider Ratio. This is the ratio of the externally supplied clock signal to the Image playback rate. For example, set this to 100 and a 1MHz external clock signal will result in a 10kHz playback rate.

If the Controller supports multiple images and playback from ImageGroup's, the ImageGroup will contain a sequence table and in that case, the Clock Divider Ratio for playing back the Image as part of a sequence may be overriden by the Clock Divider Ratio field specified in the Sequence Table.

Parameters
[in]divAn integer variable to set the Image default external Clock Divider ratio from.
Since
1.0.1
const int iMS::Image::ExtClockDivide ( ) const

Returns the default External Clock Divider Ratio associated with the Image.

The Image contains a default External Clock Divider Ratio which shall be used as the frequency ratio between the external clock signal and the Image playback frequency when the Controller is configured for External Clock mode and is not overriden by the Clock Divider Ratio specified in a sequence table.

Returns
An integer value representing the default External Clock Divier Ratio associated with an Image
Since
1.0.1
iterator iMS::Image::InsertPoint ( iterator  it,
const ImagePoint pt 
)

Inserts a single new element into the PointList.

The ImagePoint pt is inserted before the element pointed to by the iterator it.

Parameters
[in]itAn ImagePoint will be inserted before the element pointed to by this iterator.
[in]ptThe ImagePoint to insert into the Image
Since
1.0
void iMS::Image::InsertPoint ( iterator  it,
size_t  nPts,
const ImagePoint pt 
)

Inserts multiple copies of an element into the PointList.

nPts copies of the ImagePoint pt are inserted into the PointList before the element pointed to be iterator it

Parameters
[in]itMultiple ImagePoints will be inserted before the element pointed to by this iterator.
[in]nPtsThe number of copies of pt to insert
[in]ptThe ImagePoint to insert multiple copies of into the Image
Since
1.0
void iMS::Image::InsertPoint ( iterator  it,
const_iterator  first,
const_iterator  last 
)

Inserts a range of ImagePoints into the PointList.

All of the ImagePoints located between first and last are copied in order into the PointList starting before the element pointed to by iterator it.

For example,

// Create an image with 4 points initialised to 70MHz
Image img1( 4, ImagePoint(FAP(70.0,100.0,0.0)));
// Create an image with 3 points initialised to 100MHz
Image img2( 3, ImagePoint(FAP(100.0,100.0,0.0)));
// Insert all of img2 in the middle of img1
img.InsertPoint(img1.begin()+2, img2.begin(), img2.end());

img2 contains [70, 70, 100, 100, 100, 70, 70]

Parameters
[in]itA range of ImagePoints will be inserted before the element pointed to by this iterator.
[in]firstAn iterator pointing to the first in a range of ImagePoints to be inserted
[in]lastAn iterator pointing to the ImagePoint after the last ImagePoint to be inserted
Since
1.0
iterator iMS::Image::RemovePoint ( iterator  it)

Removes a single ImagePoint from the PointList.

Erases a single ImagePoint, reducing the size of the Image by one. The removed ImagePoint is destroyed.

Parameters
[in]itIterator pointing to a single ImagePoint to be removed from the PointList
Returns
An iterator pointing to the new location of the ImagePoint that followed the element erased by the function call. If the operation erased the last ImagePoint in the PointList, this will be equal to Image::end().
Since
1.0
iterator iMS::Image::RemovePoint ( iterator  first,
iterator  last 
)

Removes a range of ImagePoints from the PointList.

Erases a range of ImagePoints from the Image, reducing the size of the Image by the number of ImagePoints removed, which are destroyed.

Parameters
[in]firstAn iterator pointing to the first in a range of ImagePoints to be removed
[in]lastAn iterator pointing to the ImagePoint after the last ImagePoint to be removed
Returns
An iterator pointing to the new location of the ImagePoint that followed the last element erased by the function call. If the operation erased the last ImagePoint in the PointList, this will be equal to Image::end().
Since
1.0
int iMS::Image::Size ( ) const

Returns the number of ImagePoints in the PointList.

Returns
The number of ImagePoints in the PointList
Since
1.0

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