nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BSamples.html

110 lines
21 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Midi Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheMidiKit.html" title="The Midi Kit" /><link rel="prev" href="BMidiText.html" title="BMidiText" /><link rel="next" href="BSynth.html" title="BSynth" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BMidiText.html" title="BMidiText"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheMidiKit.html" title="The Midi Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BSynth.html" title="BSynth"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Midi Kit</div></div><div id="headerB">Prev: <a href="BMidiText.html">BMidiText</a>  Up: <a href="TheMidiKit.html">The Midi Kit</a>  Next: <a href="BSynth.html">BSynth</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples"></a>BSamples</h2></div></div></div><a id="id1201468" class="indexterm"></a><div class="classheader"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td><table width="100%" border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Derived From:</td><td>–</td></tr><tr><td>Mix-in Classes:</td><td>–</td></tr><tr><td>Declared In:</td><td><code class="filename">midi/Samples.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libmidi.so</code></td></tr><tr><td>Allocation:</td><td>–</td></tr></tbody></table></td><td>
<a class="link overview" href="BSamples_Overview.html" title="BSamples">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BSamples.html#BSamples_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BSamples.html#BSamples_MemberFunctions">Member Functions</a></span></li></ul></div>
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_ConstructorDestructor"></a>Constructor and Destructor</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_Constructor"></a>BSamples()</h4></div></div></div><code class="constructorsynopsis cpp"><span class="methodname">BSamples</span>();</code><p>Creates a new, empty <code class="classname">BSamples</code> object.
Also constructs a
<a class="link" href="BSynth.html" title="BSynth"><code class="classname">BSynth</code></a>
object and assigns the object to the app-wide
<code class="varname">be_synth</code> variable (if the object
doesn't already exist). To initialize and use the
<code class="classname">BSamples</code> object, invoke its
<a class="link" href="BSamples.html#BSamples_Start" title="Start(), sample_loop_hook, sample_exit_hook"><code class="methodname">Start()</code></a>
function.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Currently, the "samples only" synth mode
(<code class="constant">B_SAMPLES_ONLY</code>) is broken.
Unfortunately, this is the mode used by the <code class="classname">BSamples</code>
constructor if it has to create a
<code class="varname">be_synth</code>
object. The easiest way around this bug is to construct a
<a class="link" href="BMidiSynth.html" title="BMidiSynth"><code class="classname">BMidiSynth</code></a> or
<a class="link" href="BMidiSynthFile.html" title="BMidiSynthFile"><code class="classname">BMidiSynthFile</code></a>
object. If you don't need the
object, you can immediately destroy it; the fix is effected by the
object's construction.</p></div></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_Destructor"></a>~BSamples()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">~BSamples</span>();</code><p>Stops the object's playback, calls the "exit hook" function (as set by
<a class="link" href="BSamples.html#BSamples_Start" title="Start(), sample_loop_hook, sample_exit_hook"><code class="methodname">Start()</code></a>),
and destroys the object.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_MemberFunctions"></a>Member Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_EnableReverb"></a>EnableReverb()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">EnableReverb</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">reverb</span></span>);</code><p>If <code class="parameter">reverb</code> is <code class="constant">true</code>,
the object's sound data is sent through the
synthesizer's reverberator. To set the reverberation depth (for all
reverberated sound), use
<a class="link" href="BSynth.html#BSynth_SetReverb"><code class="methodname">BSynth::SetReverb()</code></a>.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_SetSamplingRate"></a><a id="BSamples_SamplingRate"></a>
<a id="BSamples_SetPlacement"></a>
<a id="BSamples_Placement"></a>
<a id="BSamples_SetVolume"></a>
<a id="BSamples_Volume"></a>
SetSamplingRate(), SamplingRate(), SetPlacement(), Placement(),
SetVolume(), Volume()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetSamplingRate</span>(<span class="methodparam"><span class="type">double </span><span class="parameter">samplingRate</span></span>);</code><code class="methodsynopsis cpp"><span class="type">double </span><span class="methodname">SamplingRate</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetPlacement</span>(<span class="methodparam"><span class="type">double </span><span class="parameter">stereoPan</span></span>);</code><code class="methodsynopsis cpp"><span class="type">double </span><span class="methodname">Placement</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetVolume</span>(<span class="methodparam"><span class="type">double </span><span class="parameter">volume</span></span>);</code><code class="methodsynopsis cpp"><span class="type">double </span><span class="methodname">Volume</span>() <span class="modifier">const</span>;</code><p>These functions set parameters of the sound data. They can be called
while the sound is playing. For details of what these parameters mean,
and the values that they accept, see the descriptions of the
<code class="parameter">samplingRate</code>, <code class="parameter">stereoPan</code>,
and <code class="parameter">volume</code> arguments of the
<a class="link" href="BSamples.html#BSamples_Start" title="Start(), sample_loop_hook, sample_exit_hook"><code class="methodname">Start()</code></a>
function.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_Start"></a><a id="sample_loop_hook"></a>
<a id="sample_exit_hook"></a>
Start(), sample_loop_hook, sample_exit_hook</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">Start</span>(<span class="methodparam"><span class="type">void* </span><span class="parameter">samples</span></span>,<br />           <span class="methodparam"><span class="type">int32 </span><span class="parameter">frameCount</span></span>,<br />           <span class="methodparam"><span class="type">int16 </span><span class="parameter">sampleSize</span></span>,<br />           <span class="methodparam"><span class="type">int16 </span><span class="parameter">channelCount</span></span>,<br />           <span class="methodparam"><span class="type">double </span><span class="parameter">samplingRate</span></span>,<br />           <span class="methodparam"><span class="type">int32 </span><span class="parameter">loopStart</span></span>,<br />           <span class="methodparam"><span class="type">int32 </span><span class="parameter">loopEnd</span></span>,<br />           <span class="methodparam"><span class="type">double </span><span class="parameter">volume</span></span>,<br />           <span class="methodparam"><span class="type">double </span><span class="parameter">stereoPan</span></span>,<br />           <span class="methodparam"><span class="type">int32 </span><span class="parameter">hookArg</span></span>,<br />           <span class="methodparam"><span class="type">sample_loop_hook </span><span class="parameter">loopHook</span></span>,<br />           <span class="methodparam"><span class="type">sample_exit_hook </span><span class="parameter">exitHook</span></span>);</code><pre class="programlisting definition c">typedef <span class="type">bool</span> (*<span class="type">sample_loop_hook</span>)(<span class="type">int32</span> <code class="parameter">arg</code>)</pre><pre class="programlisting definition c">typedef <span class="type">void</span> (*<span class="type">sample_exit_hook</span>)(<span class="type">int32</span> <code class="parameter">arg</code>)</pre><p><code class="methodname">Start()</code> passes in a buffer of audio samples that are immediately played.
The playback is performed by the synthesizer in its
<code class="classname">BSubscriber</code>
thread; the <code class="methodname">Start()</code> function itself returns
immediately.</p><p>The audio data is assumed to be little-endian linear; other parameters of
the data (sample size, channel count, etc.) are variable and are declared
in the function's arguments. The arguments are:</p><table class="variablelist parameters"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="parameter">samples</code></span></p></td><td><p>Is a pointer to the data itself.</p></td></tr><tr><td><p><span class="term"><code class="parameter">frameCount</code></span></p></td><td><p>Is the number of frames of audio data in the buffer.</p></td></tr><tr><td><p><span class="term"><code class="parameter">sampleSize</code></span></p></td><td><p>Is the size of a single sample, in bytes. Currently, the
synthesizer only accepts 1- and 2-byte samples.</p></td></tr><tr><td><p><span class="term"><code class="parameter">channelCount</code></span></p></td><td><p>Is the number of channels of data (1 or 2).</p></td></tr><tr><td><p><span class="term"><code class="parameter">samplingRate</code></span></p></td><td><p>Is the rate at which you want to the data played back,
expressed as frames-per-second; for example, if your sound data was
sampled at 44.1kHz and you want to play it back at its "native" pitch,
you would set samplingRate to 44100.0. The range of valid sampling rate
values is [0, ~65 kHz]. The sampling rate is independent of the data's
channel count and sample size, and is independent of
<code class="varname">be_synth</code>'s
sampling rate. You can change the object's sampling rate on the fly
through
<a class="link" href="BSamples.html#BSamples_SetSamplingRate" title="SetSamplingRate(), SamplingRate(), SetPlacement(), Placement(), SetVolume(), Volume()"><code class="methodname">SetSamplingRate()</code></a>.</p></td></tr><tr><td><p><span class="term"><code class="parameter">loopStart</code> and <code class="parameter">loopEnd</code></span></p></td><td><p>Specify the first and last frames that are in
the "loop section." The loop section can be any valid section of frames
within the sound data (i.e. [0, <code class="parameter">frameCount</code> - 1] inclusive). Everything
up to the beginning of the loop section is the "attack section";
everything after the loop section is the "release section." When the
sound is played, the attack section is heard, then the loop section is
repeated until the object is told to
<a class="link" href="BSamples.html#BSamples_Stop" title="Stop(), Pause(), Resume(), IsPaused(), IsPlaying()"><code class="methodname">Stop()</code></a>,
or until the "loop hook"
function (defined below) returns <code class="constant">false</code>, at which point the release
section is played. If you don't want the sound to loop, set these
loop… arguments to 0.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>Currently, the release section is automatically faded out over a brief
period of time. If your release section is designed to do a slow fade
(for example) you probably won't hear it.</p></div></div></div></td></tr><tr><td><p><span class="term"><code class="parameter">volume</code></span></p></td><td><p>Is an amplitude scalar for this sound. The volume can also be
set through
<a class="link" href="BSamples.html#BSamples_SetVolume"><code class="methodname">SetVolume()</code></a>.</p></td></tr><tr><td><p><span class="term"><code class="parameter">stereoPan</code></span></p></td><td><p>Locates the sound stereophonically, where -1.0 is hard
left, 0.0 is center, and 1.0 is hard right. Notice that if this is a
stereo sound, a <code class="parameter">stereoPan</code> value of (say) -1.0 completely attenuates the
right channel—it doesn't "move" the right channel into the left
channel.</p></td></tr><tr><td><p><span class="term"><code class="parameter">hookArg</code></span></p></td><td><p>Is an arbitrary value that's passed to the <code class="parameter">loopHook</code> and
<code class="parameter">exitHook</code> functions.</p></td></tr><tr><td><p><span class="term"><code class="parameter">loopHook</code></span></p></td><td><p>Is a hook function that's called each time the loop section
is about to repeat. If the function returns <code class="constant">true</code>, the loop is, indeed,
repeated. If it returns <code class="constant">false</code>, the release section is played and the
sound stops. If you don't supply a <code class="parameter">loopHook</code>, the loop is automatically
repeated.</p></td></tr><tr><td><p><span class="term"><code class="parameter">exitHook</code></span></p></td><td><p>Is called when the sound is all done playing, regardless of
how it stopped (whether through
<a class="link" href="BSamples.html#BSamples_Stop" title="Stop(), Pause(), Resume(), IsPaused(), IsPlaying()"><code class="methodname">Stop()</code></a>, a
<code class="parameter">hookFunc</code> return of <code class="constant">false</code>, or
because the <code class="classname">BSamples</code> object was deleted).</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BSamples_Stop"></a><a id="BSamples_Pause"></a>
<a id="BSamples_Resume"></a>
<a id="BSamples_IsPaused"></a>
<a id="BSamples_IsPlaying"></a>
Stop(), Pause(), Resume(), IsPaused(), IsPlaying()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">Stop</span>();</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">Pause</span>();</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">Resume</span>();</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsPlaying</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsPaused</span>() <span class="modifier">const</span>;</code><p><code class="methodname">Stop()</code> tells the object to stop
playing its sound data, and invokes the exit function, as set through
<a class="link" href="BSamples.html#BSamples_Start" title="Start(), sample_loop_hook, sample_exit_hook"><code class="methodname">Start()</code></a>.</p><p><code class="methodname">Pause()</code> suspends playback and
<code class="methodname">Resume()</code> resumes it from where it was
paused.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p><code class="methodname">Pause()</code> and
<code class="methodname">Resume()</code> are backwards. To pause a sound,
call <code class="methodname">Resume()</code>. To
resume it, call <code class="methodname">Pause()</code>. Sorry about that.</p></div></div></div><p><code class="methodname">IsPlaying()</code> returns <code class="constant">true</code> if the object is currently playing (paused or
not).</p><p><code class="methodname">IsPaused()</code> returns <code class="constant">true</code> if the sound is currently paused.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p><code class="methodname">IsPaused()</code> returns
<code class="constant">true</code> if you've called
<code class="methodname">Pause()</code>. Thus, since
<code class="methodname">Pause()</code> and
<code class="methodname">Resume()</code> are backwards, the sense of
<code class="methodname">IsPaused()</code> is also backwards.</p></div></div></div></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BMidiText.html">BMidiText</a>  Up: <a href="TheMidiKit.html">The Midi Kit</a>  Next: <a href="BSynth.html">BSynth</a> </div><div id="footerB"><div id="footerBL"><a href="BMidiText.html" title="BMidiText"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheMidiKit.html" title="The Midi Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BSynth.html" title="BSynth"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink