Loading...
Searching...
No Matches
ToneGen::Config Class Reference

`ToneGen` configuration data structure. More...

`#include <tonegen.h>`

Collaboration diagram for ToneGen::Config:

## Classes

struct | Freq
| Data storage for a `ToneGen` frequency component. More...
struct | Cadence
| Data storage for a `ToneGen` cadence 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.
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.
void | SetRepeat (bool repeat=true)
| Set this (sequence of) tone(s) to play once, or loop continuously.
void | ClearTones ()
| Clear all frequency and cadence data from this `Config`.
Completion notification
void | SetCompletionCallback (CompletionCallback callback)
| Request asynchronous notification of normal tone completion.
User defined data storage
template<typename T>
void | SetUserData (size_t slot, T data)
| Store arbitrary, typed data into a user-data slot.
template<typename T>
T & | GetUserData (size_t slot) const
| Retreive arbitrary, typed data from a user-data slot.
Tone data iteration
These methods provide access to tone data for `ToneGen` implementations.
const Freq::List & | GetNextFreqs ()
| Return the next frequency component in the sequence.
const Cadence & | GetNextCadence ()
| Return the next cadence timing in the sequence.

## 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

  slot | The 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::Exception | will be thrown if there is no data stored in slot.
  std::bad_cast | will 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

  onms | The 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.
  offms | The off time for a cadenced tone. Ignored unless onms is non zero.
  tnum | The 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

  callback | The 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:
  - `Start()`
  - `Stop()`
  - `BeginSequence()`
  - `SignalCompletion()`

  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:
  - `GetConfig()`
  - `ContinueSequence()`
  - `EndSequence()`

## 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

  hz | The frequency in `Hz` of this tone component.
  db | The magnitude of this tone component in `dB`, from `-inf` to `0dB`.
  fnum | The 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.
  tnum | The 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

  repeat | Loop 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,
|  | T | data )

inline

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

Parameters

  slot | A user defined index from 0 - n to use when retrieving this data element.
  data | The data to store in slot.