mirror of
https://github.com/thestk/stk
synced 2026-01-11 20:11:52 +00:00
75 lines
3.9 KiB
Plaintext
75 lines
3.9 KiB
Plaintext
/*! \page crealtime Realtime Audio (callback)
|
|
|
|
An alternative scheme for audio input/output is to define a specific
|
|
function in which audio computations are performed and to let the
|
|
audio system call this function when more input/output data can be
|
|
accepted by the hardware (referred to as a callback scheme). In this
|
|
section, we show how the previous <TT>rtsine.cpp</TT> program can be
|
|
modified to work in a callback scenario. There is no "single-sample"
|
|
interface for this functionality. The callback function will be
|
|
invoked automatically by the audio system controller (RtAudio) when
|
|
new data is needed and it is necessary to compute a full audio buffer
|
|
of samples at that time (see \ref callback for further information).
|
|
|
|
The previous section described the use of the stk::RtWvOut class for
|
|
realtime audio output. The stk::RtWvOut::tick() function writes data to a
|
|
large ring-buffer, from which data is periodically written to the
|
|
computer's audio hardware via an underlying callback routine.
|
|
|
|
\include crtsine.cpp
|
|
|
|
The sinusoidal oscillator is created as before. The instantiation of
|
|
RtAudio requires quite a few more parameters, including output/input
|
|
device and channel specifiers, the data format, and the desired buffer
|
|
length (in frames). In this example, we request a single output
|
|
channel using the default output device, zero channels of input, the
|
|
RtAudio data format which corresponds to an <tt>StkFloat</tt>, and the
|
|
RT_BUFFER_SIZE defined in Stk.h. The \c bufferFrames argument is an
|
|
API-dependent buffering parameter (see RtAudio for further
|
|
information).
|
|
|
|
We also provide the audio system controller with a pointer to our
|
|
callback function and an optional pointer to data that will be made
|
|
available in the callback. In this example, we need to pass only the
|
|
pointer to the oscillator. In more complex programs, it is typically
|
|
necessary to put all shared data in a <tt>struct</tt> (see the next
|
|
tutorial program for an example) or make use of global variables.
|
|
|
|
Our callback routine is the \c tick() function. Function arguments
|
|
include pointers to the audio input and output data buffers, the
|
|
buffer size (in frames), a stream time argument, a status argument to
|
|
test for over/underruns, and the data pointer passed in the
|
|
openStream() function (if it exists). It is necessary to cast these
|
|
pointers to their corresponding data types before use. Our tick()
|
|
routine simply "ticks" the oscillator for \c nBufferFrames counts and
|
|
writes the result into the audio data buffer before returning.
|
|
|
|
The \c main() function blocks at the std::cin.get() call until the
|
|
user hits the "enter" key, after which the audio controller is shut
|
|
down and program execution ends.
|
|
|
|
\section callback Blocking vs. Callbacks
|
|
|
|
Prior to version 4.2.0, all STK example projects and programs used
|
|
blocking audio input/output functionality (typically with the RtWvIn,
|
|
RtWvOut, or RtDuplex classes). In many instances, a blocking scheme
|
|
results in a clearer and more straight-forward program structure.
|
|
Within a graphical user interface (GUI) programming context, however,
|
|
callback routines are often more natural.
|
|
|
|
In order to allow all STK programs to function with equal proficiency
|
|
on all supported computer platforms, a decision was made to modify the
|
|
example projects to use audio callback routines. The result is a more
|
|
complicated code structure, which is unfortunate given that we
|
|
generally strive to make STK code as clear as possible for educational
|
|
purposes. This was especially an issue with the demo program because
|
|
it is designed to function in both realtime and non-realtime contexts.
|
|
The use of global variables has been avoided by defining data
|
|
structures to hold all variables that must be accessible to the
|
|
callback routine and other functions. Alternative schemes for making
|
|
control updates could be designed depending on particular program
|
|
needs and constraints.
|
|
|
|
[<A HREF="tutorial.html">Main tutorial page</A>] [<A HREF="instruments.html">Next tutorial</A>]
|
|
*/
|