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

105 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="BMidiSynth.html" title="BMidiSynth" /><link rel="next" href="BMidiText.html" title="BMidiText" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BMidiSynth.html" title="BMidiSynth"><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="BMidiText.html" title="BMidiText"><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="BMidiSynth.html">BMidiSynth</a>  Up: <a href="TheMidiKit.html">The Midi Kit</a>  Next: <a href="BMidiText.html">BMidiText</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="BMidiSynthFile"></a>BMidiSynthFile</h2></div></div></div><a id="id1199618" 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/MidiSynthFile.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="BMidiSynthFile_Overview.html" title="BMidiSynthFile">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BMidiSynthFile.html#BMidiSynthFile_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BMidiSynthFile.html#BMidiSynthFile_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="BMidiSynthFile_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="BMidiSynthFile_Constructor"></a>BMidiSynthFile()</h4></div></div></div><code class="constructorsynopsis cpp"><span class="methodname">BMidiSynthFile</span>();</code><p>Creates a new, empty <code class="classname">BMidiSynthFile</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 load a MIDI file into the
<code class="classname">BMidiSynthFile</code> object, you must call
<a class="link" href="BMidiSynthFile.html#BMidiSynthFile_LoadFile" title="LoadFile(), UnloadFile()"><code class="methodname">LoadFile()</code></a>
after construction. Unlike plain
<a class="link" href="BMidiSynth.html" title="BMidiSynth"><code class="classname">BMidiSynth</code></a>
instances, however, you don't have to call
<a class="link" href="BMidiSynth.html#BMidiSynth_EnableInput" title="EnableInput(), IsInputEnabled()"><code class="methodname">EnableInput()</code></a>
(<a class="link" href="BMidiSynthFile.html#BMidiSynthFile_LoadFile" title="LoadFile(), UnloadFile()"><code class="methodname">LoadFile()</code></a>
calls it for you).</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="BMidiSynthFile_Destructor"></a>~BMidiSynthFile()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">~BMidiSynthFile</span>();</code><p>Disconnects the object from the synthesizer, unloads the object's file
(and all its instruments) 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="BMidiSynthFile_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="BMidiSynthFile_Duration"></a><a id="BMidiSynthFile_Position"></a>
<a id="BMidiSynthFile_Seek"></a>
Duration(), Position(), Seek()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">Duration</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">Position</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">ticks</span></span>);</code><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">Seek</span>();</code><p><code class="methodname">Duration()</code> returns the length of the object's loaded data, measured in
64ths of a MIDI tick.</p><p><code class="methodname">Position()</code> sets the object's current position within the data.</p><p><code class="methodname">Seek()</code> returns the object's current position.</p><p>If you want to reposition the "song pointer", you should do it as a
percentage of the <code class="methodname">Duration()</code> measurement.</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>A MIDI tick is defined by the "MIDI Division" field at the bginning of
every MIDI file; this value can be specified by the file as either "ppgn"
(tempo-dependent) or frames:subframes per second (tempo-independent). The
<code class="classname">BMidiSynthFile</code> class assumes that the division is tempo-independent.</p></div></div></div><p>RETURN CODES</p><p>Currently <code class="methodname">Position()</code> always returns
<code class="constant">B_OK</code>.</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="BMidiSynthFile_GetPatches"></a>GetPatches()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetPatches</span>(<span class="methodparam"><span class="type">int16* </span><span class="parameter">instruments</span></span>,<br />                    <span class="methodparam"><span class="type">int16* </span><span class="parameter">count</span></span>);</code><p>Returns an array of the instruments numbers that are needed by the loaded
MIDI file. The <code class="parameter">instruments</code> array should be 128 elements long (to be on
the safe side), and must be allocated before it's passed in. Upon return,
the function sets <code class="parameter">count</code> to the number of instrument numbers that it placed in
the array. For example:</p><pre class="programlisting example cpp"><span class="type">int16</span> <code class="varname">insts</code>[128];
<span class="type">int16</span> <code class="varname">count</code>;
<code class="varname">midiSynthFile</code>.<code class="methodname">GetPatches</code>(<code class="varname">insts</code>, &amp;<code class="varname">count</code>);
for (<span class="type">int</span> <code class="varname">n</code> = 0; <code class="varname">n</code> &lt; <code class="varname">count</code>; <code class="varname">n</code>++)
<code class="function">printf</code>("The file uses instrument #%d\n", <code class="varname">insts</code>[<code class="varname">n</code>]);</pre></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="BMidiSynthFile_LoadFile"></a><a id="BMidiSynthFile_UnloadFile"></a>
LoadFile(), UnloadFile()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">LoadFile</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref* </span><span class="parameter">midiFileRef</span></span>);</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">UnloadFile</span>() <span class="modifier">const</span>;</code><p><code class="methodname">LoadFile()</code> tells the object to load, into the synthesizer, the MIDI data
from the <code class="parameter">midiFileRef</code>. The synthesizer caches the data for subsequent
playback (which you initiate through
Start()).
All instruments that are needed to play the file are loaded into the synthesizer, if they're
aren't loaded already.</p><p><code class="methodname">UnloadFile()</code> stops playback of the data that was loaded through this
object (if it's playing), and flushes the data (removes it from the
synthesizer).</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>In certain circumstances, a single <code class="classname">BMidiSynthFile</code>
object can load and play more than one MIDI file at the same time, but you shouldn't rely on
this feature.</p></div></div></div><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 file was found and loaded.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_MIDI_DATA</code></span></p></td><td><p><code class="parameter">midiFileRef</code> isn't a MIDI file, or contains corrupt data.</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 load the file.</p></td></tr><tr><td><p><span class="term"> Other POSIX errors.</span></p></td><td><p>The file couldn't be opened or read.</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="BMidiSynthFile_MuteTrack"></a><a id="BMidiSynthFile_GetMuteMap"></a>
<a id="BMidiSynthFile_SoloTrack"></a>
<a id="BMidiSynthFile_GetSoloMap"></a>
MuteTrack(), GetMuteMap(), SoloTrack(), GetSoloMap()</h4></div></div></div><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>These functions are broken; don't use them.</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="BMidiSynthFile_Start"></a><a id="BMidiSynthFile_Stop"></a>
<a id="BMidiSynthFile_Fade"></a>
<a id="BMidiSynthFile_Pause"></a>
<a id="BMidiSynthFile_Resume"></a>
<a id="BMidiSynthFile_IsFinished"></a>
<a id="BMidiSynthFile_EnableLooping"></a>
<a id="BMidiSynthFile_SetFileHook"></a>
<a id="synth_file_hook"></a>
Start(), Stop(), Fade(), Pause(), Resume(), IsFinished(),
EnableLooping(), SetFileHook(), synth_file_hook</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">Start</span>();</code><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">Fade</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">IsFinished</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">EnableLooping</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">loop</span></span>);</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetFileHook</span>(<span class="methodparam"><span class="type">synth_file_hook </span><span class="parameter">fileDone</span></span>,<br />                 <span class="methodparam"><span class="type">int32 </span><span class="parameter">arg</span></span>);</code><pre class="programlisting definition c">typedef <span class="type">void</span> (*<span class="type">synth_file_hook</span>)(<span class="type">int32</span> <code class="parameter">arg</code>)</pre><p>These functions control the object's performance.</p><p><code class="methodname">Start()</code> tells the synthesizer to start
playing the object's loaded MIDI data beginning at the beginning. Note that
<code class="methodname">Start()</code> does not halt a performance in
progress; in other words, if the object is already playing its data, you'll
get a second, performance while the first continues.</p><p><code class="methodname">Stop()</code> immediately halts the currently
playing data. <code class="methodname">Fade()</code> also stops playback, but
is a bit more graceful: It fades out the sound before killing it.</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="classname">BMidiSynthFile</code>'s
<code class="methodname">Start()</code> and <code class="methodname">Stop()</code>
replace the functions defined by
<code class="classname">BMidi</code>;
in particular, they spawn and control a "run" thread. See
"<a class="xref" href="BMidiSynthFile_Overview.html#BMidiSynthFile_Overview_TheRunThreadAndFunction" title="The Run Thread and Function">The Run Thread and Function</a>"
for more information.</p></div></div></div><p><code class="methodname">Pause()</code> and
<code class="methodname">Resume()</code> do as they say. Note that when you
resume playback, "old" notes are not regenerated, but exact
timing is respected. For example, lets say you have a MIDI file that
contains two notes, one that starts at time 1.0 (seconds) and lasts for
10.0 seconds, and the other starts at time 9.0. You start the file, then
<code class="methodname">Pause()</code> at time 3.0; as expected, the first
note stops. After awhile, you <code class="methodname">Resume()</code>;
there's a six second silence and then the second note plays.</p><p><code class="methodname">IsFinished()</code> returns
<code class="constant">false</code> if the object is currently playing (or
paused during play). Note that the function returns
<code class="constant">false</code> before you load a file, and returns
<code class="constant">true</code> after you've loaded a file but before you
begin playing it.</p><p><span class="code"><code class="methodname">EnableLooping</code>(<code class="constant">true</code>)</span>
tells the object to replay the file when it reaches the end of the data. If
the argument is <code class="constant">false</code>, the file isn't replayed.
<code class="methodname">Stop()</code> always shuts up playback, even if
looping is enabled.</p><p><code class="methodname">SetFileHook()</code> registers a function
that's called when the object is finished playing (either because it ran
out of data or <code class="methodname">Stop()</code> was called. arg is
passed to the hook function as its sole argument. Note that the hook
function is called when the object is completely finished—it isn't
called at the end of each pass through the data while looping is
enabled.</p><p><code class="methodname">Start()</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>Success.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_TOO_MANY_SONGS_PLAYING</code></span></p></td><td><p>The synthesizer is too busy with other data streams.</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="BMidiSynthFile_Tempo"></a><a id="BMidiSynthFile_SetTempo"></a>
<a id="BMidiSynthFile_ScaleTempoBy"></a>
Tempo(), SetTempo(), ScaleTempoBy()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">int32 </span><span class="methodname">Tempo</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">SetTempo</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">beatsPerMinute</span></span>);</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">ScaleTempoBy</span>(<span class="methodparam"><span class="type">double </span><span class="parameter">scalar</span></span>);</code><p><code class="methodname">Tempo()</code> returns the tempo of the data,
as read from the MIDI file (or as set by the other functions), in
beats-per-minute. The other two functions set the tempo:
<code class="methodname">SetTempo()</code> sets it absolutely in
beats-per-minute, and <code class="methodname">ScaleTempoBy()</code> scales
the current tempo by the argument (scalar == 2.0 means the data is played
twice as fast, scalar == .5 is twice as slow, and so on).</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BMidiSynth.html">BMidiSynth</a>  Up: <a href="TheMidiKit.html">The Midi Kit</a>  Next: <a href="BMidiText.html">BMidiText</a> </div><div id="footerB"><div id="footerBL"><a href="BMidiSynth.html" title="BMidiSynth"><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="BMidiText.html" title="BMidiText"><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