e1lama/stk
1
0
Fork 0
mirror of https://github.com/thestk/stk synced 2026-01-15 14:01:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Release 4.4.0 tarball

Browse Source
This commit is contained in:
Gary Scavone
2013-09-29 23:44:33 +02:00
committed by Stephen Sinclair
parent 3706458166
commit d2ed001eb5
1427 changed files with 44061 additions and 39976 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
doc/html/instruments.html
View File

@@ -8,17 +8,19 @@
<img src="princeton.gif"> &nbsp; <img src="ccrma.gif"> &nbsp; <img src="mcgill.gif"><P>
<a class="qindex" href="index.html">Home</a> &nbsp; <a class="qindex" href="information.html">Information</a> &nbsp; <a class="qindex" href="classes.html">Classes</a> &nbsp; <a class="qindex" href="download.html">Download</a> &nbsp; <a class="qindex" href="usage.html">Usage</a> &nbsp; <a class="qindex" href="maillist.html">Mail List</a> &nbsp; <a class="qindex" href="system.html">Requirements</a> &nbsp; <a class="qindex" href="links.html">Links</a> &nbsp; <a class="qindex" href="faq.html">FAQ</a> &nbsp; <a class="qindex" href="tutorial.html">Tutorial</a></CENTER>
<HR>
<!-- Generated by Doxygen 1.4.4 -->
<h1><a class="anchor" name="instruments">Instruments</a></h1>The ToolKit comes with a wide variety of synthesis algorithms, all of which inherit from the <a class="el" href="classInstrmnt.html">Instrmnt</a> class. In this example, we'll fire up an instance of the <a class="el" href="classBeeThree.html">BeeThree</a> <a class="el" href="classFM.html">FM</a> synthesis class and show how its frequency can be modified over time.<p>
<!-- Generated by Doxygen 1.5.8 -->
<div class="contents">
<h1><a class="anchor" name="instruments">Instruments </a></h1>The ToolKit comes with a wide variety of synthesis algorithms, all of which inherit from the <a class="el" href="classstk_1_1Instrmnt.html" title="STK instrument abstract base class.">stk::Instrmnt</a> class. In this example, we'll fire up an instance of the <a class="el" href="classstk_1_1BeeThree.html" title="STK Hammond-oid organ FM synthesis instrument.">stk::BeeThree</a> FM synthesis class and show how its frequency can be modified over time.<p>
<div class="fragment"><pre class="fragment"><span class="comment">// bethree.cpp STK tutorial program</span>
<span class="preprocessor">#include "BeeThree.h"</span>
<span class="preprocessor">#include "<a class="code" href="RtAudio_8h.html">RtAudio.h</a>"</span>
<span class="keyword">using namespace </span>stk;
<span class="comment">// The TickData structure holds all the class instances and data that</span>
<span class="comment">// are shared by the various processing functions.</span>
<span class="keyword">struct </span>TickData {
<a class="code" href="classInstrmnt.html">Instrmnt</a> *instrument;
Instrmnt *instrument;
StkFloat frequency;
StkFloat scaler;
<span class="keywordtype">long</span> counter;
@@ -33,7 +35,7 @@
<span class="comment">// called automatically when the system needs a new buffer of audio</span>
<span class="comment">// samples.</span>
<span class="keywordtype">int</span> tick( <span class="keywordtype">void</span> *outputBuffer, <span class="keywordtype">void</span> *inputBuffer, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> nBufferFrames,
<span class="keywordtype">double</span> streamTime, <a class="code" href="RtAudio_8h.html#a11">RtAudioStreamStatus</a> status, <span class="keywordtype">void</span> *userData )
<span class="keywordtype">double</span> streamTime, <a class="code" href="RtAudio_8h.html#80e306d363583da3b0a1b65d9b57c806" title="RtAudio stream status (over- or underflow) flags.">RtAudioStreamStatus</a> status, <span class="keywordtype">void</span> *userData )
{
TickData *data = (TickData *) userData;
<span class="keyword">register</span> StkFloat *samples = (StkFloat *) outputBuffer;
@@ -55,31 +57,31 @@
<span class="keywordtype">int</span> main()
{
<span class="comment">// Set the global sample rate and rawwave path before creating class instances.</span>
<a class="code" href="classStk.html#e1">Stk::setSampleRate</a>( 44100.0 );
<a class="code" href="classStk.html#e3">Stk::setRawwavePath</a>( <span class="stringliteral">"../../rawwaves/"</span> );
Stk::setSampleRate( 44100.0 );
Stk::setRawwavePath( <span class="stringliteral">"../../rawwaves/"</span> );
TickData data;
<a class="code" href="classRtAudio.html">RtAudio</a> dac;
<a class="code" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> dac;
<span class="comment">// Figure out how many bytes in an StkFloat and setup the RtAudio stream.</span>
<a class="code" href="structRtAudio_1_1StreamParameters.html">RtAudio::StreamParameters</a> parameters;
parameters.<a class="code" href="structRtAudio_1_1StreamParameters.html#o0">deviceId</a> = dac.<a class="code" href="classRtAudio.html#a5">getDefaultOutputDevice</a>();
parameters.<a class="code" href="structRtAudio_1_1StreamParameters.html#o1">nChannels</a> = 1;
<a class="code" href="RtAudio_8h.html#a0">RtAudioFormat</a> format = ( <span class="keyword">sizeof</span>(StkFloat) == 8 ) ? RTAUDIO_FLOAT64 : RTAUDIO_FLOAT32;
<a class="code" href="structRtAudio_1_1StreamParameters.html" title="The structure for specifying input or ouput stream parameters.">RtAudio::StreamParameters</a> parameters;
parameters.<a class="code" href="structRtAudio_1_1StreamParameters.html#ffd27496c70c0986522056234c64e28e">deviceId</a> = dac.<a class="code" href="classRtAudio.html#3a3f3dbe13ea696b521e49cdaaa357bc" title="A function that returns the index of the default output device.">getDefaultOutputDevice</a>();
parameters.<a class="code" href="structRtAudio_1_1StreamParameters.html#78798b65fada7941e1a7e47c11c9e627">nChannels</a> = 1;
<a class="code" href="RtAudio_8h.html#afca92882d25915560018873221e44b8" title="RtAudio data format type.">RtAudioFormat</a> format = ( <span class="keyword">sizeof</span>(StkFloat) == 8 ) ? RTAUDIO_FLOAT64 : RTAUDIO_FLOAT32;
<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> bufferFrames = RT_BUFFER_SIZE;
<span class="keywordflow">try</span> {
dac.<a class="code" href="classRtAudio.html#a7">openStream</a>( &amp;parameters, NULL, format, (<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span>)Stk::sampleRate(), &amp;bufferFrames, &amp;tick, (<span class="keywordtype">void</span> *)&amp;data );
dac.<a class="code" href="classRtAudio.html#facc99740fa4c5606fb35467cdea6da8" title="A public function for opening a stream with the specified parameters.">openStream</a>( &amp;parameters, NULL, format, (<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span>)Stk::sampleRate(), &amp;bufferFrames, &amp;tick, (<span class="keywordtype">void</span> *)&amp;data );
}
<span class="keywordflow">catch</span> ( <a class="code" href="classRtError.html">RtError</a>&amp; error ) {
error.<a class="code" href="classRtError.html#a2">printMessage</a>();
<span class="keywordflow">catch</span> ( <a class="code" href="classRtError.html" title="Exception handling class for RtAudio &amp;amp; RtMidi.">RtError</a>&amp; error ) {
error.<a class="code" href="classRtError.html#da41f7472122f45bc5b4677f066e0943" title="Prints thrown error message to stderr.">printMessage</a>();
<span class="keywordflow">goto</span> cleanup;
}
<span class="keywordflow">try</span> {
<span class="comment">// Define and load the BeeThree instrument</span>
data.instrument = <span class="keyword">new</span> <a class="code" href="classBeeThree.html">BeeThree</a>();
data.instrument = <span class="keyword">new</span> BeeThree();
}
<span class="keywordflow">catch</span> ( <a class="code" href="classStkError.html">StkError</a> &amp; ) {
<span class="keywordflow">catch</span> ( StkError &amp; ) {
<span class="keywordflow">goto</span> cleanup;
}
@@ -87,23 +89,23 @@
data.instrument-&gt;noteOn( data.frequency, 0.5 );
<span class="keywordflow">try</span> {
dac.<a class="code" href="classRtAudio.html#a9">startStream</a>();
dac.<a class="code" href="classRtAudio.html#ec017a89629ccef66a90b60be22a2f80" title="A function that starts a stream.">startStream</a>();
}
<span class="keywordflow">catch</span> ( <a class="code" href="classRtError.html">RtError</a> &amp;error ) {
error.<a class="code" href="classRtError.html#a2">printMessage</a>();
<span class="keywordflow">catch</span> ( <a class="code" href="classRtError.html" title="Exception handling class for RtAudio &amp;amp; RtMidi.">RtError</a> &amp;error ) {
error.<a class="code" href="classRtError.html#da41f7472122f45bc5b4677f066e0943" title="Prints thrown error message to stderr.">printMessage</a>();
<span class="keywordflow">goto</span> cleanup;
}
<span class="comment">// Block waiting until callback signals done.</span>
<span class="keywordflow">while</span> ( !data.done )
<a class="code" href="classStk.html#e7">Stk::sleep</a>( 100 );
Stk::sleep( 100 );
<span class="comment">// Shut down the callback and output stream.</span>
<span class="keywordflow">try</span> {
dac.<a class="code" href="classRtAudio.html#a8">closeStream</a>();
dac.<a class="code" href="classRtAudio.html#90d599002ad32cf250a4cb866f2cc93a" title="A function that closes a stream and frees any associated stream memory.">closeStream</a>();
}
<span class="keywordflow">catch</span> ( <a class="code" href="classRtError.html">RtError</a> &amp;error ) {
error.<a class="code" href="classRtError.html#a2">printMessage</a>();
<span class="keywordflow">catch</span> ( <a class="code" href="classRtError.html" title="Exception handling class for RtAudio &amp;amp; RtMidi.">RtError</a> &amp;error ) {
error.<a class="code" href="classRtError.html#da41f7472122f45bc5b4677f066e0943" title="Prints thrown error message to stderr.">printMessage</a>();
}
cleanup:
@@ -112,14 +114,15 @@
<span class="keywordflow">return</span> 0;
}
</pre></div><p>
We have used an <a class="el" href="classInstrmnt.html">Instrmnt</a> pointer when referencing the <a class="el" href="classBeeThree.html">BeeThree</a> instance above, so it would be simple to replace the <a class="el" href="classBeeThree.html">BeeThree</a> class with any other STK instrument class. It should be noted, however, that a few classes do not respond to the setFrequency() function (e.g., <a class="el" href="classShakers.html">Shakers</a>, <a class="el" href="classDrummer.html">Drummer</a>).<p>
The noteOn() function initiates an instrument attack. Instruments that are continuously excited (e.g., <a class="el" href="classClarinet.html">Clarinet</a>, <a class="el" href="classBeeThree.html">BeeThree</a>) will continue to sound until stopped with a noteOff(). Impulsively excited instrument sounds (e.g., <a class="el" href="classPlucked.html">Plucked</a>, <a class="el" href="classWurley.html">Wurley</a>) typically decay within a few seconds time, requiring subsequent noteOn() messages for re-attack.<p>
We have used an Instrmnt pointer when referencing the BeeThree instance above, so it would be simple to replace the BeeThree class with any other STK instrument class. It should be noted, however, that a few classes do not respond to the setFrequency() function (e.g., Shakers, Drummer).<p>
The noteOn() function initiates an instrument attack. Instruments that are continuously excited (e.g., <a class="el" href="classstk_1_1Clarinet.html" title="STK clarinet physical model class.">stk::Clarinet</a>, <a class="el" href="classstk_1_1BeeThree.html" title="STK Hammond-oid organ FM synthesis instrument.">stk::BeeThree</a>) will continue to sound until stopped with a noteOff(). Impulsively excited instrument sounds (e.g., <a class="el" href="classstk_1_1Plucked.html" title="STK plucked string model class.">stk::Plucked</a>, <a class="el" href="classstk_1_1Wurley.html" title="STK Wurlitzer electric piano FM synthesis instrument.">stk::Wurley</a>) typically decay within a few seconds time, requiring subsequent noteOn() messages for re-attack.<p>
Instrument parameters can be precisely controlled as demonstrated above. A more flexible approach to instrument control, allowing arbitrary scorefile or realtime updates, is described in the next tutorial chapter.<p>
[<a href="tutorial.html">Main tutorial page</a>] &nbsp; [<a href="controlin.html">Next tutorial</a>] <HR>
[<a href="tutorial.html">Main tutorial page</a>] &nbsp; [<a href="controlin.html">Next tutorial</a>] </div>
<HR>
<table>
<tr><td><A HREF="http://ccrma.stanford.edu/software/stk/"><I>The Synthesis ToolKit in C++ (STK)</I></A></td></tr>
<tr><td>&copy;1995-2007 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
<tr><td>&copy;1995-2009 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
</table>
</BODY>