libvpb
4.2.61
|
ToneGen
configuration data structure.
More...
#include <tonegen.h>
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 | |
const Freq::List & | GetNextFreqs () |
Return the next frequency component in the sequence. More... | |
const Cadence & | GetNextCadence () |
Return the next cadence timing in the sequence. More... | |
Friends | |
class | ToneGen |
ToneGen-only methods | |
Config () | |
Default constructor. | |
~Config () | |
Destructor. | |
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.
|
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.
|
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().
|
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().
|
inline |
Retreive arbitrary, typed data from a user-data slot.
slot | The user defined index from 0 - n that was used to store the data with a call to SetUserData() . |
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().
|
inline |
Set the on and off time in ms
for a cadenced tone.
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.
|
inline |
Request asynchronous notification of normal tone completion.
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.
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()
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:
|
inline |
Set one of the component frequencies for a tone.
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.
|
inline |
Set this (sequence of) tone(s) to play once, or loop continuously.
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.
|
inline |
Store arbitrary, typed data into a user-data slot.
slot | A user defined index from 0 - n to use when retrieving this data element. |
data | The data to store in slot. |