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

201 lines
36 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="BSamples.html" title="BSamples" /><link rel="next" href="TheMidiKit_GeneralMIDIInstruments.html" title="General MIDI Instruments" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BSamples.html" title="BSamples"><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="TheMidiKit_GeneralMIDIInstruments.html" title="&#10;General MIDI Instruments"><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="BSamples.html">BSamples</a>  Up: <a href="TheMidiKit.html">The Midi Kit</a>  Next: <a href="TheMidiKit_GeneralMIDIInstruments.html">
General MIDI Instruments</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="BSynth"></a>BSynth</h2></div></div></div><a id="id1202749" 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/Synth.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="BSynth_Overview.html" title="BSynth">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BSynth.html#BSynth_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BSynth.html#BSynth_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="BSynth_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="BSynth_Constructor"></a>BSynth()</h4></div></div></div><div class="synopsisgroup">
<code class="constructorsynopsis cpp"><span class="methodname">BSynth</span>();</code>
<code class="constructorsynopsis cpp"><span class="methodname">BSynth</span>(<span class="methodparam"><span class="type">synth_mode </span><span class="parameter">mode</span></span>);</code>
</div><p>Creates and initiailzes a new <code class="classname">BSynth</code>
object and sets <code class="varname">be_synth</code> to point to
it. The <code class="classname">BSynth</code> that
<code class="varname">be_synth</code> currently points to (if any) is deleted. You
can only construct one <code class="classname">BSynth</code> object per application. Every application
that wants to use the synthesizer must have its own <code class="classname">BSynth</code>—you
can't "share" another application's <code class="varname">be_synth</code> object. The constructors for
the other synthesis classes
(<a class="link" href="BMidiSynth.html" title="BMidiSynth"><code class="classname">BMidiSynth</code></a>,
<a class="link" href="BMidiSynthFile.html" title="BMidiSynthFile"><code class="classname">BMidiSynthFile</code></a>, and
<a class="link" href="BSamples.html" title="BSamples"><code class="classname">BSamples</code></a>)
create a <code class="classname">BSynth</code> for you if one doesn't already exist.</p><p>The default constructor sets the following synthesis parameters, shown
here with the functions that you can use to reset the values—and
that you should refer to for further explanation:</p><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Parameter</th><th>Value</th><th>Function</th></tr></thead><tbody><tr><td>Output sampling rate</td><td>22 kHz</td><td><a class="link" href="BSynth.html#BSynth_SetSamplingRate" title="SetSamplingRate(), SamplingRate(), SetInterpolation(), Interpolation(), interpolation_mode"><code class="methodname">SetSamplingRate()</code></a></td></tr><tr><td>Sample interpolation</td><td><code class="constant">B_LINEAR_INTERPOLATION</code></td><td><a class="link" href="BSynth.html#BSynth_SetInterpolation"><code class="methodname">SetInterpolation()</code></a></td></tr><tr><td>Max synth voices</td><td>28</td><td><a class="link" href="BSynth.html#BSynth_SetVoiceLimits" title="SetVoiceLimits(), MaxSynthVoices(), MaxSampleVoices(), LimiterThreshhold()"><code class="methodname">SetVoiceLimits()</code></a></td></tr><tr><td>Max sample voices</td><td>4</td><td><a class="link" href="BSynth.html#BSynth_SetVoiceLimits" title="SetVoiceLimits(), MaxSynthVoices(), MaxSampleVoices(), LimiterThreshhold()"><code class="methodname">SetVoiceLimits()</code></a></td></tr><tr><td>Limiter threshhold</td><td>7</td><td><a class="link" href="BSynth.html#BSynth_SetVoiceLimits" title="SetVoiceLimits(), MaxSynthVoices(), MaxSampleVoices(), LimiterThreshhold()"><code class="methodname">SetVoiceLimits()</code></a></td></tr><tr><td>Reverb enabled</td><td><code class="constant">true</code></td><td><a class="link" href="BSynth.html#BSynth_EnableReverb" title="EnableReverb(), IsReverbEnabled(), SetReverb(), Reverb(), reverb_mode"><code class="methodname">EnableReverb()</code></a></td></tr><tr><td>Reverb</td><td><code class="constant">B_REVERB_BALLROOM</code></td><td><a class="link" href="BSynth.html#BSynth_SetReverb"><code class="methodname">SetReverb()</code></a></td></tr><tr><td>Synth mode</td><td><code class="constant">B_SYNTH_NONE</code></td><td><a class="link" href="BSynth.html#BSynth_LoadSynthData" title="LoadSynthData(), Unload(), SynthMode(), IsLoaded()"><code class="methodname">LoadSynthData()</code></a></td></tr></tbody></table></div><p>You must call
<a class="link" href="BSynth.html#BSynth_LoadSynthData" title="LoadSynthData(), Unload(), SynthMode(), IsLoaded()"><code class="methodname">LoadSynthData()</code></a>
after calling the default constructor to set the synth mode.</p><p>The <span class="type">synth_mode</span> constructor sets the synthesis parameters (as above) and
then sets the synth mode to the argument, one of <code class="constant">B_BIG_SYNTH</code>,
<code class="constant">B_LITTLE_SYNTH</code>, or <code class="constant">B_SAMPLES_ONLY</code>. See
<a class="link" href="BSynth.html#BSynth_LoadSynthData" title="LoadSynthData(), Unload(), SynthMode(), IsLoaded()"><code class="methodname">LoadSynthData()</code></a>
for <span class="type">synth_mode</span> definitions.</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="BSynth_Destructor"></a>~BSynth()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">~BSynth</span>();</code><p>The destructor stops the synthesizer if it's currently playing anything,
frees all synthesis-related storage that the <code class="classname">BSynth</code> object allocated, and
sets <code class="varname">be_synth</code> to point to <code class="constant">NULL</code>.</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="BSynth_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="BSynth_CountClients"></a>CountClients()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">CountClients</span>() <span class="modifier">const</span>;</code><p>Returns the number of synthesis objects
(<a class="link" href="BMidiSynth.html" title="BMidiSynth"><code class="classname">BMidiSynth</code></a> and
<a class="link" href="BMidiSynthFile.html" title="BMidiSynthFile"><code class="classname">BMidiSynthFile</code></a>)
that are actively feeding data to the synthesizer. Note that this count
does not include
<a class="link" href="BSamples.html" title="BSamples"><code class="classname">BSamples</code></a>
objects.</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="BSynth_EnableReverb"></a><a id="BSynth_IsReverbEnabled"></a>
<a id="BSynth_SetReverb"></a>
<a id="BSynth_Reverb"></a>
<a id="reverb_mode"></a>
<a id="B_REVERB_NONE"></a>
<a id="B_REVERB_CLOSET"></a>
<a id="B_REVERB_GARAGE"></a>
<a id="B_REVERB_BALLROOM"></a>
<a id="B_REVERB_CAVERN"></a>
<a id="B_REVERB_DUNGEON"></a>
EnableReverb(), IsReverbEnabled(), SetReverb(), Reverb(), reverb_mode</h4></div></div></div><a id="id1203470" class="indexterm"></a><a id="id1203477" class="indexterm"></a><a id="id1203486" class="indexterm"></a><a id="id1203496" class="indexterm"></a><a id="id1203505" class="indexterm"></a><a id="id1203514" class="indexterm"></a><a id="id1203523" class="indexterm"></a><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">EnableReverb</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">reverb_enabled</span></span>);</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsReverbEnabled</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetReverb</span>(<span class="methodparam"><span class="type">reverb_mode </span><span class="parameter">reverb</span></span>);</code><code class="methodsynopsis cpp"><span class="type">reverb_mode </span><span class="methodname">Reverb</span>() <span class="modifier">const</span>;</code><pre class="programlisting definition c">typedef enum {
<code class="constant">B_REVERB_NONE</code>, <code class="constant">B_REVERB_CLOSET</code>,
<code class="constant">B_REVERB_GARAGE</code>, <code class="constant">B_REVERB_BALLROOM</code>,
<code class="constant">B_REVERB_CAVERN</code>, <code class="constant">B_REVERB_DUNGEON</code>
} <span class="type">reverb_mode</span></pre><p><code class="methodname">EnableReverb()</code> turns on and off
<code class="varname">be_synth</code>'s reverberator.
<code class="methodname">IsReverbEnabled()</code> returns the current
reverberator-enabled state. Reverb is enabled by default.</p><p><code class="methodname">SetReverb()</code> sets the reverberator's
strength. The constants, shown above, are listed in order of increasing
"wetness." <code class="methodname">Reverb()</code> returns the
current setting. Setting the reverb mode doesn't enable the
reverberator.</p><p>To turn off the reverberator, do this:</p><pre class="programlisting example c"><code class="methodname">EnableReverb</code>(<code class="constant">false</code>); <span class="comment">/* Good */</span></pre><p>…rather than:</p><pre class="programlisting example c"><code class="methodname">SetReverb</code>(<code class="constant">B_REVERB_NONE</code>); <span class="comment">/* Bad */</span></pre><p><code class="methodname">EnableReverb()</code> returns…</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>The reverberator was successfully enabled/disabled.</p></td></tr><tr><td><p><span class="term">Thread and port error codes.<code class="constant">B_NO_MEMORY</code></span></p></td><td><p>Not enough memory to setup the reverberator.</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="BSynth_GetAudio"></a>GetAudio()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">GetAudio</span>(<span class="methodparam"><span class="type">int16 </span><span class="parameter">left</span></span>,<br />               <span class="methodparam"><span class="type">int16 </span><span class="parameter">right</span></span>,<br />               <span class="methodparam"><span class="type">int32 </span><span class="parameter">sampleCount</span></span>) <span class="modifier">const</span>;</code><p>Returns, in <code class="parameter">left</code> and <code class="parameter">right</code>,
the last <code class="parameter">sampleCount</code>'th sample frames (split
into left and right channels) generated by the synthesizer. Storage for
the samples must be allocated by the caller. The function may return
fewer samples than requested. The function returns the number of samples
that were written into (each of) <code class="parameter">left</code> and
<code class="parameter">right</code>.</p><p>This function is designed to feed waveform displays (and the like); it
isn't intended to be used as a "sound spigot" that you can pipe to a file
(for example).</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="BSynth_LoadSynthData"></a><a id="BSynth_Unload"></a>
<a id="BSynth_SynthMode"></a>
<a id="BSynth_IsLoaded"></a>
<a id="synth_mode"></a>
LoadSynthData(), Unload(), SynthMode(), IsLoaded()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">LoadSynthData</span>(<span class="methodparam"><span class="type">synth_mode </span><span class="parameter">mode</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">LoadSynthData</span>(<span class="methodparam"><span class="type">entry_ref* </span><span class="parameter">instrument_file</span></span>);</code>
</div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">Unload</span>();</code><code class="methodsynopsis cpp"><span class="type">synth_mode </span><span class="methodname">SynthMode</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">IsLoaded</span>() <span class="modifier">const</span>;</code><p><code class="methodname">LoadSynthData()</code> tells
<code class="varname">be_synth</code> which synth file to use (and unloads the
one currently in use, if any). The first version lets you specify the
synth file through a <span class="type">synth_mode</span> constant:</p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_BIG_SYNTH</code></span></p></td><td><p>Use the big synth file.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LITTLE_SYNTH</code></span></p></td><td><p>Use the little synth file.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_SAMPLES_ONLY</code></span></p></td><td><p>Don't use a synth file, but prepare the object so it
can play sampled sounds. You only use this mode if you're only going to
use the <a class="link" href="BSamples.html" title="BSamples"><code class="classname">BSamples</code></a>
object (in other words, if you're not using
<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>).</p></td></tr></tbody></table><p>If the synthesizer is initialized with a synth file, it will
automatically know how to play
<a class="link" href="BSamples.html" title="BSamples"><code class="classname">BSamples</code></a>
data.</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, <code class="constant">B_SAMPLES_ONLY</code> doesn't work.
You must use one of the other two constants
(<code class="constant">B_BIG_SYNTH</code> or <code class="constant">B_LITTLE_SYNTH</code>).</p></div></div></div><p>The second version lets you set the synth file as an <span class="type">entry_ref</span>, thus
providing the opportunity to specify a custom synth file. Unfortunately,
the synth file format isn't currently public, so you can't create your
own synth files (yet).</p><p><code class="methodname">LoadSynthData()</code> doesn't actually
read the instrument definitions from the
synth file—in other words, it doesn't really "load" anything. The
instruments are loaded as needed during a performance (as specified by a
<code class="classname">BMidiSynth[File]</code> object). To force instruments to be read, use
<a class="link" href="BMidiSynth.html" title="BMidiSynth"><code class="classname">BMidiSynth</code></a>'s
<a class="link" href="BMidiSynth.html#BMidiSynth_EnableInput" title="EnableInput(), IsInputEnabled()"><code class="methodname">EnableInput()</code></a> or
<a class="link" href="BMidiSynth.html#BMidiSynth_LoadInstrument" title="LoadInstrument(), RemapInstrument(), UnloadInstrument(), FlushInstrumentCache()"><code class="methodname">LoadInstrument()</code></a>
function.</p><p><code class="methodname">Unload()</code> stops the synthesizer (if
it's currently playing), forgets the instrument file that was used to
initialize the synthesizer, and steps out of the audio output mechanism.
After you call <code class="methodname">Unload()</code>, the
<code class="varname">be_synth</code> object
is good for nothing until <code class="methodname">LoadSynthData()</code>
is called (whether directly or through a constructor).</p><p><code class="methodname">SynthMode()</code> returns
<code class="varname">be_synth</code>'s current synth mode, one of the three modes
listed above or <code class="constant">B_NO_SYNTH</code> if the mode hasn't been set.</p><p><code class="methodname">IsLoaded()</code> returns
<code class="constant">true</code> if <code class="varname">be_synth</code>
has been initialized and is ready to go. Otherwise, it returns
<code class="constant">false</code>.</p><p><code class="methodname">LoadSynthData()</code> returns…</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p><code class="varname">be_synth</code>
was successfully initialized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>Invalid argument.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code></span></p></td><td><p>Not enough memory to initialize the synthesizer.</p></td></tr><tr><td><p><span class="term">POSIX errors</span></p></td><td><p>The synth file wasn't found or couldn't be opened.</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="BSynth_Pause"></a><a id="BSynth_Resume"></a>
Pause(), Resume()</h4></div></div></div><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><p><code class="methodname">Pause()</code> tells the synthesizer
to stop producing sound. It doesn't suspend non-synthesis
<a class="link" href="BMidi.html" title="BMidi"><code class="classname">BMidi</code></a>
objects—in other words, <code class="methodname">Pause()</code> doesn't suspend
<a class="link" href="BMidiPort.html" title="BMidiPort"><code class="classname">BMidiPort</code></a> or
<a class="link" href="BMidiStore.html" title="BMidiStore"><code class="classname">BMidiStore</code></a>
objects.</p><p><code class="methodname">Resume()</code> tells the synthesizer to
resume producing sound.
<a class="link" href="BMidiSynthFile.html" title="BMidiSynthFile"><code class="classname">BMidiSynthFile</code></a>
objects continue reading from where they were paused;
<a class="link" href="BSamples.html" title="BSamples"><code class="classname">BSamples</code></a>
objects start playing from the beginning of their sample data (they don't
continue from where they were paused).</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="BSynth_SetControllerHook"></a><a id="synth_controller_hook"></a>
SetControllerHook(), synth_controller_hook</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetControllerHook</span>(<span class="methodparam"><span class="type">int16 </span><span class="parameter">controller</span></span>,<br />                       <span class="methodparam"><span class="type">synth_controller_hook </span><span class="parameter">controlHook</span></span>);</code><pre class="programlisting definition c">typedef <span class="type">void</span> (*<span class="type">synth_controller_hook</span>)(<span class="type">int16</span> <code class="parameter">channel</code>, <span class="type">int16</span> <code class="parameter">controller</code>,
<span class="type">int16</span> <code class="parameter">value</code>)</pre><p>Registers a hook function (<code class="parameter">controlHook</code>)
that's invoked whenver a <acronym class="acronym">MIDI</acronym>
control message is applied to controller. The hook function is invoked
just after the control message is processed by the synthesizer. The
function is passed the channel, controller number, and controller value
as taken from the control message.</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="BSynth_SetSamplingRate"></a><a id="BSynth_SamplingRate"></a>
<a id="BSynth_SetInterpolation"></a>
<a id="BSynth_Interpolation"></a>
<a id="Enums_interpolation_mode"></a>
<a id="B_DROP_SAMPLE"></a>
<a id="B_2_POINT_INTERPOLATION"></a>
<a id="B_LINEAR_INTERPOLATION"></a>
SetSamplingRate(), SamplingRate(), SetInterpolation(),
Interpolation(), interpolation_mode</h4></div></div></div><a id="id1204540" class="indexterm"></a><a id="id1204547" class="indexterm"></a><a id="id1204556" class="indexterm"></a><a id="id1204566" class="indexterm"></a><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetSamplingRate</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">rate</span></span>);</code><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">SamplingRate</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetInterpolation</span>(<span class="methodparam"><span class="type">interpolation_mode </span><span class="parameter">interp</span></span>);</code><code class="methodsynopsis cpp"><span class="type">interpolation_mode </span><span class="methodname">Interpolation</span>() <span class="modifier">const</span>;</code><pre class="programlisting definition c">typedef enum {
<code class="constant">B_DROP_SAMPLE</code>,
<code class="constant">B_2_POINT_INTERPOLATION</code>,
<code class="constant">B_LINEAR_INTERPOLATION</code>
} <span class="type">interpolation_mode</span></pre><p><code class="methodname">SetSamplingRate()</code> sets the frequency at
which <code class="varname">be_synth</code> produces data, in
frames (of audio data) per second. Acceptable rates are 44100, 22050, and
11025; rate is rounded to the nearest acceptable value. The default is
22050.</p><p><code class="methodname">SamplingRate()</code> returns the sampling rate as previously set by
<code class="methodname">SetSamplingRate()</code>.</p><p><code class="varname">be_synth</code>'s sampling rate is
independent of the <acronym class="acronym">DAC</acronym> stream's sampling
rate. For example, while the default be_synth rate is 22050, the default
<acronym class="acronym">DAC</acronym> stream rate is 44100. If the two rates don't
match, <code class="varname">be_synth</code>'s
<code class="classname">BSubscriber</code> object "interpolates" th
<code class="varname">be_synth</code> data before dumping it
into the <acronym class="acronym">DAC</acronym> stream. There are three interpolation schemes, which you set
through <code class="methodname">SetInterpolation()</code>:</p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_DROP_SAMPLE</code></span></p></td><td><p>Samples are repeated or dropped. It sounds cheap because it
is cheap.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_2_POINT_INTERPOLATION</code></span></p></td><td><p>Linear interpolation between adjacent samples.
Much better quality, and more expensive, than drop-sample.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LINEAR_INTERPOLATION</code></span></p></td><td><p>"Wide" linear interpolation. The best quality, but
the most expensive.</p></td></tr></tbody></table><p><code class="methodname">Interpolation()</code> returns the current interpolation mode setting. The
default is <code class="constant">B_LINEAR_INTERPOLATION</code>.</p><p><code class="methodname">SetSamplingRate()</code> and
<code class="methodname">SetInterpolation()</code> return…</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>The function was successful.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>Invalid argument.</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="BSynth_SetSynthVolume"></a><a id="BSynth_SetSampleVolume"></a>
<a id="BSynth_SynthVolume"></a>
<a id="BSynth_SampleVolume"></a>
SetSynthVolume(), SetSampleVolume(), SynthVolume(), SampleVolume()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetSynthVolume</span>(<span class="methodparam"><span class="type">double </span><span class="parameter">scale</span></span>);</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetSampleVolume</span>(<span class="methodparam"><span class="type">double </span><span class="parameter">scale</span></span>);</code><code class="methodsynopsis cpp"><span class="type">double </span><span class="methodname">SynthVolume</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">double </span><span class="methodname">SampleVolume</span>() <span class="modifier">const</span>;</code><p>These functions get and set the master volume scalars for <acronym class="acronym">MIDI</acronym> synthesis
and <a class="link" href="BSamples.html" title="BSamples"><code class="classname">BSamples</code></a>
playback. The scalar is linear: A <code class="parameter">scale</code> of 1.0 (the default)
has no affect; a <code class="parameter">scale</code> of 2.0 multiplies the output by 2.0, and so on.
The <code class="parameter">scale</code> value must be at least 0.0 (no gain).</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="BSynth_SetVoiceLimits"></a><a id="BSynth_MaxSynthVoices"></a>
<a id="BSynth_MaxSampleVoices"></a>
<a id="BSynth_LimiterThreshhold"></a>
SetVoiceLimits(), MaxSynthVoices(), MaxSampleVoices(),
LimiterThreshhold()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetVoiceLimits</span>(<span class="methodparam"><span class="type">int16 </span><span class="parameter">maxSynthVoices</span></span>,<br />                        <span class="methodparam"><span class="type">int16 </span><span class="parameter">maxSampleVoices</span></span>,<br />                        <span class="methodparam"><span class="type">int16 </span><span class="parameter">limiterThreshhold</span></span>);</code><code class="methodsynopsis cpp"><span class="type">int16 </span><span class="methodname">MaxSynthVoices</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">int16 </span><span class="methodname">MaxSampleVoices</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">int16 </span><span class="methodname">LimiterThreshhold</span>() <span class="modifier">const</span>;</code><p>The synthesizer can generate as many as 32 "voices" simultaneously, where
a voice is a <acronym class="acronym">MIDI</acronym> note or a stream of
<a class="link" href="BSamples.html" title="BSamples"><code class="classname">BSamples</code></a>.
The first two arguments
tell the synthesizer to set aside some number of voice slots for <acronym class="acronym">MIDI</acronym>
synthesis and for samples, respectively; combined, the two arguments
mustn't exceed 32. If you ask for too many voices during a performance,
the synthesizer will (try to) kill old voices first. By default, the
voices are allocated 28 for <acronym class="acronym">MIDI</acronym> synthesis and 4 for samples.</p><p>You use the <code class="parameter">limiterThreshhold</code> to estimate the typical voice density
(number of simultaneous voices) for a performance. It must be at least 1;
the default is 7. The synthesizer uses the value as an amplitude scalar:</p><ul class="itemizedlist"><li><p>When the voice density during a performance is less than (or equal
to) the threshhold (<em class="replaceable"><code>n</code></em>), the dynamic range is "divided" into <em class="replaceable"><code>n</code></em> parts,
where each voice gets one part.</p></li><li><p>When the voice density (<em class="replaceable"><code>m</code></em>) exceeds the threshhold, the dynamic range
is divided into <em class="replaceable"><code>m</code></em> parts.</p></li></ul><p>If you set the value too high (if there are typically fewer simultaneous
voices than you estimated) the signal-to-noise ratio will
suffer—you'll be dividing the dynamic range into too many (small)
parts. If you set it too low and the voice density changes a lot, the
balance between voices may become hard to predict and control. A change
to the <code class="parameter">limiterTreshhold</code> doesn't affect notes/samples that are currently
being produced.</p><p>The other three functions return the values that you passed to
<code class="methodname">SetVoiceLimits()</code>. Note that these functions don't actually consult the
synthsizer—if you pass illegal values to <code class="methodname">SetVoiceLimits()</code>, the
querying functions will return those values without complaint.</p><p><code class="methodname">SetVoiceLimits()</code> returns…</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>The limits were successfully set.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>Bad argument value; the previous settings are left
unchanged.</p></td></tr></tbody></table></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BSamples.html">BSamples</a>  Up: <a href="TheMidiKit.html">The Midi Kit</a>  Next: <a href="TheMidiKit_GeneralMIDIInstruments.html">
General MIDI Instruments</a> </div><div id="footerB"><div id="footerBL"><a href="BSamples.html" title="BSamples"><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="TheMidiKit_GeneralMIDIInstruments.html" title="&#10;General MIDI Instruments"><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