QtFM::VoiceHandle Class

The VoiceHandle class controls a voice that Engine::play() started. More…

List of all members, including inherited members

Public Functions

Detailed Description

A handle is weak: it stays safe to use after the voice ends, and after the engine is destroyed, when its calls do nothing. Every call is thread-safe and non-blocking.

PlayOptions engineOptions;
engineOptions.delay = 2.3f;
VoiceHandle hum = engine.play(Patch::generate(Category::Engine, 42), engineOptions);
auto *rev = new QTimer(&app);
QElapsedTimer clock;
clock.start();
QObject::connect(rev, &QTimer::timeout, &app, [hum, &clock]() mutable {
    const float t = float(clock.elapsed()) / 1000.0f - 2.3f;
    hum.setPitch(std::clamp(t * 6.0f, 0.0f, 14.0f)); // smoothed on the audio thread
    if (t > 3.0f)
        hum.stop();
});
rev->start(20);

Differences from Qt

Member Function Documentation

QtFM::VoiceHandle::VoiceHandle()

Constructs a handle that refers to no voice.

QtFM::VoiceHandle::VoiceHandle(const VoiceHandle &other)

Constructs a copy of other, referring to the same voice.

QtFM::VoiceHandle::~VoiceHandle()

Destroys the handle. The voice plays on.

quint32 QtFM::VoiceHandle::id() const

Returns the identifier of the voice, as Engine::voiceFinished() gives it, or 0.

bool QtFM::VoiceHandle::isPlaying() const

Returns true while the voice waits to start or plays.

bool QtFM::VoiceHandle::isValid() const

Returns true if the handle refers to a voice, even one that has ended.

VoiceHandle & QtFM::VoiceHandle::operator=(const VoiceHandle &other)

Makes this handle refer to the voice of other, and returns a reference to it.

void QtFM::VoiceHandle::setGain(float dB)

Sets the gain of the voice to dB.

void QtFM::VoiceHandle::setPan(float pan)

Sets the pan of the voice to pan, from -1 (left) to 1 (right).

void QtFM::VoiceHandle::setParameter(ParamId id, float value)

Sets the parameter id of the voice to value. The change is smoothed over about 5 ms.

void QtFM::VoiceHandle::setParameterAt(ParamId id, float value, quint64 frame)

Sets the parameter id of the voice to value at the absolute frame of the engine's output, as Engine::frame() counts it; a frame already rendered applies it at once. A scheduler such as MidiPlayer places controller changes on their samples this way.

See also QtFM::Engine::playAt().

void QtFM::VoiceHandle::setPitch(float semitones)

Sets the pitch of the voice to semitones above the note it started on.

void QtFM::VoiceHandle::stop(bool immediate = false)

Releases the voice, which then fades out through its release envelope; if immediate is true, it fades out in 2 ms instead.