libvpb  4.2.61
ToneGen::Config Class Reference

ToneGen configuration data structure. More...

#include <tonegen.h>

Collaboration diagram for ToneGen::Config:
Collaboration graph

Classes

struct  Cadence
 Data storage for a ToneGen cadence component. More...
 
struct  Freq
 Data storage for a ToneGen frequency component. More...
 

Public Member Functions

Tone configuration
void SetFreq (unsigned int hz, float db=0.0, unsigned int fnum=0, unsigned int tnum=0)
 Set one of the component frequencies for a tone. More...
 
void SetCadence (unsigned int onms, unsigned int offms=0, unsigned int tnum=0)
 Set the on and off time in ms for a cadenced tone. More...
 
void SetRepeat (bool repeat=true)
 Set this (sequence of) tone(s) to play once, or loop continuously. More...
 
void ClearTones ()
 Clear all frequency and cadence data from this Config. More...
 
Completion notification
void SetCompletionCallback (CompletionCallback callback)
 Request asynchronous notification of normal tone completion. More...
 
User defined data storage
template<typename T >
void SetUserData (size_t slot, T data)
 Store arbitrary, typed data into a user-data slot. More...
 
template<typename T >
T & GetUserData (size_t slot) const
 Retreive arbitrary, typed data from a user-data slot. More...
 
Tone data iteration

These methods provide access to tone data for ToneGen implementations.

const Freq::ListGetNextFreqs ()
 Return the next frequency component in the sequence. More...
 
const CadenceGetNextCadence ()
 Return the next cadence timing in the sequence. More...
 

Friends

class ToneGen
 

ToneGen-only methods

 Config ()
 Default constructor.
 
 ~Config ()
 Destructor.
 

Detailed Description

ToneGen configuration data structure.

This is kept separate from the ToneGen itself so that parameters can be composed independently and applied to a shared ToneGen object atomically.

Member Function Documentation

◆ ClearTones()

void ToneGen::Config::ClearTones ( )
inline

Clear all frequency and cadence data from this Config.

This method may be used to partially clear an existing Config for reuse with a new set of tones. Any previously set CompletionCallback or UserData will be unaffected by it.

Note
It mostly is only useful when composing a SEQUENCE of tones for a ToneGen, and is unsafe to call once the Config object has been passed to one unless that ToneGen's mutex is locked. The only time that is guaranteed to the user application at present is in the scope of a CompletionCallback call.

◆ GetNextCadence()

const Cadence& ToneGen::Config::GetNextCadence ( )
inline

Return the next cadence timing in the sequence.

This function is used by the various ToneGen implementations to retrieve the configuration data for the next discrete tone to generate. You should not usually call it from a user application.

Bounds checking is done by the HasCompleted() method which should be called when each discrete tone generates a completion event at the end of its cadence cycle.

Referenced by V4PCIToneGen::ImplStart().

◆ GetNextFreqs()

const Freq::List& ToneGen::Config::GetNextFreqs ( )
inline

Return the next frequency component in the sequence.

This function is used by the various ToneGen implementations to retrieve the configuration data for the next set of frequencies to generate. You should not usually call it from a user application.

Bounds checking is done by the HasCompleted() method which should be called when each discrete tone generates a completion event at the end of its cadence cycle.

Referenced by V4PCIToneGen::ImplStart().

◆ GetUserData()

template<typename T >
T& ToneGen::Config::GetUserData ( size_t  slot) const
inline

Retreive arbitrary, typed data from a user-data slot.

Parameters
slotThe user defined index from 0 - n that was used to store the data with a call to SetUserData().
Returns
A reference to the data stored. This means that you may alter the data in place if desired, as well as inspecting it.
Exceptions
ToneGen::Exceptionwill be thrown if there is no data stored in slot.
std::bad_castwill be thrown if the data in slot is not of type T.

Referenced by V4PCIToneGen::ImplStart().

◆ SetCadence()

void ToneGen::Config::SetCadence ( unsigned int  onms,
unsigned int  offms = 0,
unsigned int  tnum = 0 
)
inline

Set the on and off time in ms for a cadenced tone.

Parameters
onmsThe on time for this tone in ms. If the on time is 0 (or no cadence is explicitly specified for some tone) then the tone generated will be continuous, and any off time will be ignored. Such a tone must be explicitly explicitly terminated by the user application at the appropriate time.
offmsThe off time for a cadenced tone. Ignored unless onms is non zero.
tnumThe index of the tone to apply this cadence to, from 0 to t-1, where t is the number of discrete sequential tones in a complex tone.

References ToneGen::Config::Cadence::offms, and ToneGen::Config::Cadence::onms.

◆ SetCompletionCallback()

void ToneGen::Config::SetCompletionCallback ( CompletionCallback  callback)
inline

Request asynchronous notification of normal tone completion.

Parameters
callbackThe function to call.

No notification will be sent to the callback if the tone generator is stopped by an explicit call from the user, such as to Stop(). Only normal completion of a (usually cadenced) tone will invoke this signalling mechanism.

Note
The callback will be invoked with the ToneGen mutex locked. This means you are guaranteed that the ToneGen object passed as its argument will have this Config set for the duration of its scope. It also means that the callback function must not call, or cause to be called, any ToneGen method that would also try to take the lock, such as:
In general, a callback for a ONESHOT tone should never try to begin any new activity on the same ToneGen. If it must play some new tone or continue the existing one, then a SEQUENCE, started with BeginSequence() should be used instead. The following ToneGen functions are safe to call from the callback:

◆ SetFreq()

void ToneGen::Config::SetFreq ( unsigned int  hz,
float  db = 0.0,
unsigned int  fnum = 0,
unsigned int  tnum = 0 
)
inline

Set one of the component frequencies for a tone.

Parameters
hzThe frequency in Hz of this tone component.
dbThe magnitude of this tone component in dB, from -inf to 0dB.
fnumThe index of the frequency to set, from 0 to n-1, where n is the number of discrete frequency components employed to generate some single tone.
tnumThe index of the tone that this frequency is a component for, from 0 to t-1, where t is the number of discrete sequential tones in a complex tone.

References ToneGen::Config::Freq::db, and ToneGen::Config::Freq::hz.

◆ SetRepeat()

void ToneGen::Config::SetRepeat ( bool  repeat = true)
inline

Set this (sequence of) tone(s) to play once, or loop continuously.

Parameters
repeatLoop continuously if true.

By default, cadenced tones will not repeat and will signal completion at the end of one full cycle. Tones that are set to loop with this method must be explicitly terminated by the user application at the appropriate time.

This option is mostly useful when composing sequences with complex tones and/or complex cadences that should play continuously. For continuous single tones, simply set a cadence on-time of 0 (which is its default value) instead.

◆ SetUserData()

template<typename T >
void ToneGen::Config::SetUserData ( size_t  slot,
data 
)
inline

Store arbitrary, typed data into a user-data slot.

Parameters
slotA user defined index from 0 - n to use when retrieving this data element.
dataThe data to store in slot.