memartel_loc/SyndicatQuebecoisdelaConstructionSimulator2021
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
65e56c8678
SyndicatQuebecoisdelaConstr.../SQCSim2021/external/irrKlang-1.6.0/doc/cpp/index.html
Marc-Eric Martel df3441dad6 Ajouts de musique et irrKlang.
2021-10-19 10:27:59 -04:00

668 lines
63 KiB
HTML
Raw Blame History

<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>irrKlang: irrKlang 1.6.0 API documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.1 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li class="current"><a href="index.html"><span>Main&nbsp;Page</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<img id="MSearchSelect" src="search/search.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</div>
</li>
</ul>
</div>
</div>
<div class="contents">
<h1>irrKlang 1.6.0 API documentation</h1><div align="center"><div align="center">
<img src="logobig.png" alt="logobig.png"/>
</div>
</div><h2><a class="anchor" id="contents">
Contents</a></h2>
<p>General:<br/>
<a class="el" href="index.html#intro">Introduction</a> <br/>
<a class="el" href="index.html#features">Features of irrKlang</a> <br/>
<a class="el" href="index.html#links">Links into the API documentation</a> <br/>
<a class="el" href="index.html#tipsandtricks">Tips and Tricks</a> <br/>
<br/>
Programming irrKlang:<br/>
<a class="el" href="index.html#concept">Starting up the Engine</a> <br/>
<a class="el" href="index.html#playingSounds">Playing Sounds</a> <br/>
<a class="el" href="index.html#changingSounds">Influencing Sounds during Playback</a> <br/>
<a class="el" href="index.html#soundSources">Using Sound Sources</a> <br/>
<a class="el" href="index.html#sound3d">3D Sound</a> <br/>
<a class="el" href="index.html#removingSounds">Removing Sounds</a> <br/>
<a class="el" href="index.html#events">Using Sound Events</a> <br/>
<a class="el" href="index.html#memoryPlayback">Memory Playback</a> <br/>
<a class="el" href="index.html#effects">Sound Effects</a> <br/>
<a class="el" href="index.html#fileOverriding">Overriding File Access</a> <br/>
<a class="el" href="index.html#audioDecoders">Adding Audio Decoders</a> <br/>
<a class="el" href="index.html#plugins">Creating irrKlang Plugins</a> <br/>
<a class="el" href="index.html#staticLib">Using irrKlang as static Lib</a> <br/>
<a class="el" href="index.html#enumeratingDevices">Enumerating sound devices</a> <br/>
<a class="el" href="index.html#recordingAudio">Recording Audio</a> <br/>
<a class="el" href="index.html#unicode">Unicode support</a> <br/>
<br/>
Short full examples:<br/>
<a class="el" href="index.html#quickstartexample">Quick Start Example</a> <br/>
<a class="el" href="index.html#quickstartexample2">Quick Start Example 2</a> <br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="intro">
Introduction</a></h2>
<p>Welcome to the irrKlang API documentation. This page should give you a short overview over irrKlang, the high level audio library. In this documentation files you'll find any information you'll need to develop applications with irrKlang using C++. If you are looking for a tutorial on how to start, you'll find some on the homepage of irrKlang at <a href="http://www.ambiera.com/irrklang">http://www.ambiera.com/irrklang</a> or inside the SDK in the directory .</p>
<p>The irrKlang library is intended to be an easy-to-use 3d and 2d sound engine, so this documentation is an important part of it. If you have any questions or suggestions, please take a look into the ambiera.com forum or just send a mail.</p>
<p><br/>
<br/>
</p>
<h2><a class="anchor" id="features">
Features of irrKlang</a></h2>
<p>irrKlang is a high level 2D and 3D cross platform sound engine and audio library. It has a very simply object orientated interface and was designed to be used in games, scientific simulations, architectural visualizations and similar. irrKlang plays several file formats such as </p>
<ul>
<li>
RIFF WAVE (*.wav) </li>
<li>
Ogg Vorbis (*.ogg) </li>
<li>
MPEG-1 Audio Layer 3 (*.mp3) </li>
<li>
Free Lossless Audio Codec (*.flac) </li>
<li>
Amiga Modules (*.mod) </li>
<li>
Impulse Tracker (*.it) </li>
<li>
Scream Tracker 3 (*.s3d) </li>
<li>
Fast Tracker 2 (*.xm) </li>
</ul>
<p>It is also able to run on different operating systems and use several output drivers: </p>
<ul>
<li>
Windows 98, ME, NT 4, 2000, XP, Vista, Windows 7, Windows 8 <ul>
<li>
DirectSound </li>
<li>
DirectSound8 </li>
<li>
WinMM </li>
</ul>
</li>
<li>
Linux / *nix <ul>
<li>
ALSA </li>
</ul>
</li>
<li>
MacOSX (x86 and PPC) <ul>
<li>
CoreAudio </li>
</ul>
</li>
</ul>
<p><br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="links">
Links into the API documentation</a></h2>
<p><a class="el" href="classirrklang_1_1_i_sound_engine.html" title="Interface to the sound engine, for playing 3d and 2d sound and music.">irrklang::ISoundEngine</a>: The main class of irrKlang.<br/>
<a href="annotated.html">Class list</a>: List of all classes with descriptions.<br/>
<a href="functions.html">Class members</a>: Good place to find forgotten features.<br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="tipsandtricks">
Tips and Tricks</a></h2>
<p>This section lists a few tips you might consider when implementing the sound part of your application using irrKlang:</p>
<ul>
<li>
If you can choose which audio file format is the primary one for your application, use .OGG files, instead of for example .MP3 files. irrKlang uses a lot less memory and CPU power when playing .OGGs. </li>
<li>
To keep your application simple, each time you play a sound, you can use for example play2D("filename.mp3") and let irrKlang handle the rest. There is no need to implement a preloading/caching/file management system for the audio playback. irrKlang will handle all this by itself and will never load a file twice. </li>
<li>
irrKlang is crashing in your application? This should not happen, irrKlang is pretty stable, and in most cases, this is a problem in your code: In a lot of cases the reason is simply a wrong call to <a class="el" href="classirrklang_1_1_i_ref_counted.html#a869fe3adc6e49e8da105e95837a565b1">irrklang::IRefCounted::drop()</a>. Be sure you are doing it correctly. (If you are unsure, tempoarily remove all calls to <a class="el" href="classirrklang_1_1_i_ref_counted.html#a869fe3adc6e49e8da105e95837a565b1">irrklang::IRefCounted::drop()</a> and see if this helps.) </li>
</ul>
<p><br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="concept">
Starting up the Engine</a></h2>
<p>irrKlang is designed so that it is very easy to achieve everything, its interface should be very simple to use. The <a class="el" href="index.html#quickstartexample">Quick Start Example</a> shows how to play and mp3 file, and there is another example, <a class="el" href="index.html#quickstartexample2">Quick Start Example 2</a>, showing some few more details.<br/>
To start up the sound engine, you simply need to call <a class="el" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">createIrrKlangDevice()</a>. To shut it down, call IRefCounted::drop():</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;<a class="code" href="irr_klang_8h.html" title="Main header file of the irrKlang sound library, the only file needed to include.">irrKlang.h</a>&gt;</span>
<span class="comment">// ...</span>
<span class="comment">// start up the engine</span>
<a class="code" href="classirrklang_1_1_i_sound_engine.html" title="Interface to the sound engine, for playing 3d and 2d sound and music.">irrklang::ISoundEngine</a>* engine = <a class="code" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">irrklang::createIrrKlangDevice</a>();
<span class="comment">// ...</span>
<span class="comment">// after finished,</span>
<span class="comment">// close the engine again, similar as calling &apos;delete&apos;</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_ref_counted.html#a869fe3adc6e49e8da105e95837a565b1">drop</a>();
</pre></div><p>The <a class="el" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">createIrrKlangDevice()</a> function also accepts several parameters, so that you can specify which sound driver should be used, if plugins should be used, if irrKlang should run in multithreaded mode, and similar. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="playingSounds">
Playing Sounds</a></h2>
<p>Once you have irrKlang running (like in <a class="el" href="index.html#concept">Starting up the Engine</a>), you can start playing sounds:</p>
<div class="fragment"><pre class="fragment"> engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;someSoundFile.wav&quot;</span>);
</pre></div><p>This works with all supported file types. You can replace "someSoundFile.wav" with "someSoundFile.mp3", or "someSoundFile.ogg", for example.<br/>
To play a sound looped, set the second parameter to 'true':</p>
<div class="fragment"><pre class="fragment"> engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;myMusic.mp3&quot;</span>, <span class="keyword">true</span>);
</pre></div><p>To stop this looping sound again, use engine-&gt;<a class="el" href="classirrklang_1_1_i_sound_engine.html#a38dbc2f1d49e3127fc4a81a9c1a2f82d">stopAllSounds()</a> to stop all sounds, or <a class="el" href="classirrklang_1_1_i_sound.html#a108485fe64658441cecd70917782961f" title="Will stop the sound and free its resources.">irrklang::ISound::stop()</a> if you only want to stop that single sound. <a class="el" href="index.html#changingSounds">Influencing Sounds during Playback</a> shows how to get to that ISound interface. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="changingSounds">
Influencing Sounds during Playback</a></h2>
<p>To influence parameters of the sound such as pan, volume or playback speed during runtime, to get the play position or stop playback of single playing sounds, you can use the <a class="el" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a> interface. <a class="el" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">irrklang::ISoundEngine::play2D</a> (but also play3D) returns a pointer to this interface when its third ('startPaused') or fourth ('track') parameter was set to true:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a>* snd = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;myMusic.mp3&quot;</span>, <span class="keyword">true</span>, <span class="keyword">false</span>, <span class="keyword">true</span>);
<span class="comment">// ...</span>
<span class="keywordflow">if</span> (snd)
snd-&gt;<a class="code" href="classirrklang_1_1_i_sound.html#a4c91357775f1d15e2c276ced09a40599" title="sets the volume of the sound, a value between 0 (mute) and 1 (full volume).">setVolume</a>(someNewValue);
<span class="comment">// ...</span>
<span class="keywordflow">if</span> (snd)
{
snd-&gt;<a class="code" href="classirrklang_1_1_i_virtual_ref_counted.html#a6602c3d110f23410c5bca8a08b709aa4" title="Drops the object. Decrements the reference counter by one.">drop</a>(); <span class="comment">// don&apos;t forget to release the pointer once it is no longer needed by you</span>
snd = 0;
}
</pre></div><p>The <a class="el" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a> interface can also be used to test if the sound has been finished, set event receivers, pause and unpause sounds and similar. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="soundSources">
Using Sound Sources</a></h2>
<p>To be more flexible playing back sounds, irrKlang uses the concept of sound sources. A sound source can be simply the name of a sound file, such as "sound.wav". It is possible to add "sound.wav" as sound source to irrKlang, and play it using the sound source pointer:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1_i_sound_source.html" title="A sound source describes an input file (.ogg, .mp3, .wav or similar) and its default...">irrklang::ISoundSource</a>* shootSound = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a4eed0fa6712872e55003b26462e21005" title="Adds sound source into the sound engine as file.">addSoundSourceFromFile</a>(<span class="stringliteral">&quot;shoot.wav&quot;</span>);
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(shootSound);
<span class="comment">// note: you don&apos;t need to drop() the shootSound if you don&apos;t use it anymore</span>
</pre></div><p>The advantage of using <a class="el" href="classirrklang_1_1_i_sound_source.html" title="A sound source describes an input file (.ogg, .mp3, .wav or similar) and its default...">irrklang::ISoundSource</a> is that it is possible to set default values for this source, such as volume or distances if it should be used as 3D sound:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1_i_sound_source.html" title="A sound source describes an input file (.ogg, .mp3, .wav or similar) and its default...">irrklang::ISoundSource</a>* shootSound = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a4eed0fa6712872e55003b26462e21005" title="Adds sound source into the sound engine as file.">addSoundSourceFromFile</a>(<span class="stringliteral">&quot;shoot.wav&quot;</span>);
shootSound-&gt;<a class="code" href="classirrklang_1_1_i_sound_source.html#a52accb16b3a554558f12f99d16f57a7d" title="Sets the default volume for a sound played from this source.">setDefaultVolume</a>(0.5f);
<span class="comment">// shootSound will now be played with half its sound volume by default:</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(shootSound);
</pre></div><p>It is also possible to have multiple settings for the same sound file:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1_i_sound_source.html" title="A sound source describes an input file (.ogg, .mp3, .wav or similar) and its default...">irrklang::ISoundSource</a>* shootSound = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a4eed0fa6712872e55003b26462e21005" title="Adds sound source into the sound engine as file.">addSoundSourceFromFile</a>(<span class="stringliteral">&quot;shoot.wav&quot;</span>);
<a class="code" href="classirrklang_1_1_i_sound_source.html" title="A sound source describes an input file (.ogg, .mp3, .wav or similar) and its default...">irrklang::ISoundSource</a>* shootSound2 = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a1a3542b9d4e1c0a77d7cc9591c3c9321" title="Adds a sound source as alias for an existing sound source, but with a different name...">addSoundSourceAlias</a>(shootSound, <span class="stringliteral">&quot;silentShoot&quot;</span>);
shootSound2-&gt;<a class="code" href="classirrklang_1_1_i_sound_source.html#a52accb16b3a554558f12f99d16f57a7d" title="Sets the default volume for a sound played from this source.">setDefaultVolume</a>(0.1f);
<span class="comment">// shootSound will now be played with 100% of its sound volume by default,</span>
<span class="comment">// shootSound2 will now be played 10% of its sound volume by default. It is </span>
<span class="comment">// also possible to play it using engine-&gt;play(&quot;silentShoot&quot;), now.</span>
</pre></div><p>Using addSoundSourceFromMemory(), it is also possible to play sounds back directly from memory, without files. Of course, it is not necessary to use sound sources. Using <a class="el" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a>, it is possible to change the settings of all sounds, too. But using sound sources, it is not necessary to do this every time a sound is played. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="sound3d">
3D Sound</a></h2>
<p>There is nothing difficult in playing sounds in 3D using irrKlang: Instead of using <a class="el" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">irrklang::ISoundEngine::play2D()</a>, just use <a class="el" href="classirrklang_1_1_i_sound_engine.html#adb09ecc8f61120ce14d26545ed43d8ec" title="Loads a sound source (if not loaded already) from a file and plays it as 3D sound...">irrklang::ISoundEngine::play3D()</a>, which takes a 3D position as additional parameter:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1vec3d.html" title="a 3d vector template class for representing vectors and points in 3d">irrklang::vec3df</a> position(23,70,90);
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#adb09ecc8f61120ce14d26545ed43d8ec" title="Loads a sound source (if not loaded already) from a file and plays it as 3D sound...">play3D</a>(<span class="stringliteral">&quot;yourSound.wav&quot;</span>, position);
</pre></div><p>But to make it sound realistic, you need to set a minimal sound distance: If your sound is caused by a bee, it will usually have a smaller sound radius than for example a jet engine. You can set default values using sound sources (see <a class="el" href="index.html#soundSources">Using Sound Sources</a>) or set these values after you have started the sound paused:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1vec3d.html" title="a 3d vector template class for representing vectors and points in 3d">irrklang::vec3df</a> position(23,70,90);
<span class="comment">// start the sound paused:</span>
<a class="code" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a>* snd = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#adb09ecc8f61120ce14d26545ed43d8ec" title="Loads a sound source (if not loaded already) from a file and plays it as 3D sound...">play3D</a>(<span class="stringliteral">&quot;yourSound.wav&quot;</span>, position, <span class="keyword">false</span>, <span class="keyword">true</span>);
<span class="keywordflow">if</span> (snd)
{
snd-&gt;<a class="code" href="classirrklang_1_1_i_sound.html#a318bcb0ec6c44078cdee3c9b080b6f41" title="Sets the minimal distance if this is a 3D sound.">setMinDistance</a>(30.0f); <span class="comment">// a loud sound</span>
snd-&gt;<a class="code" href="classirrklang_1_1_i_sound.html#a399fef60d1c48e2dffdf76d83173a15a" title="returns if the sound is paused">setIsPaused</a>(<span class="keyword">false</span>); <span class="comment">// unpause the sound</span>
}
</pre></div><p>There is also the possibility to change the maxDistance, but it is only necessary to change this in very rare cicumstances. If the sound moves, it is also a good idea to update its position from time to time:</p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (snd)
snd-&gt;<a class="code" href="classirrklang_1_1_i_sound.html#a994b98c059e8aee6adb82bb12d866338" title="sets the position of the sound in 3d space">setPosition</a>(newPosition);
</pre></div><p>And don't forget to drop() the sound after you don't need it anymore. If you do, it's nothing severe because irrKlang will still clean up the sounds resources after it has finished, but you still would waste some few bytes of memory:</p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (snd)
{
snd-&gt;<a class="code" href="classirrklang_1_1_i_virtual_ref_counted.html#a6602c3d110f23410c5bca8a08b709aa4" title="Drops the object. Decrements the reference counter by one.">drop</a>();
snd = 0;
}
</pre></div><p>To update the position of yourself, the listener of the 3D sounds, use this from time to time:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1vec3d.html" title="a 3d vector template class for representing vectors and points in 3d">irrklang::vec3df</a> position(0,0,0); <span class="comment">// position of the listener</span>
<a class="code" href="classirrklang_1_1vec3d.html" title="a 3d vector template class for representing vectors and points in 3d">irrklang::vec3df</a> lookDirection(10,0,10); <span class="comment">// the direction the listener looks into</span>
<a class="code" href="classirrklang_1_1vec3d.html" title="a 3d vector template class for representing vectors and points in 3d">irrklang::vec3df</a> velPerSecond(0,0,0); <span class="comment">// only relevant for doppler effects</span>
<a class="code" href="classirrklang_1_1vec3d.html" title="a 3d vector template class for representing vectors and points in 3d">irrklang::vec3df</a> upVector(0,1,0); <span class="comment">// where &apos;up&apos; is in your 3D scene</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#af3e6223435969159ef3b22d0c83d2b84" title="Sets the current listener 3d position.">setListenerPosition</a>(position, lookDirection, velPerSecond, upVector);
</pre></div><p><br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="removingSounds">
Removing Sounds</a></h2>
<p>irrKlang manages the memory usage of sounds by itself, so usually, you don't have to care about memory management. But if you know you need to reduce the amount of used memory at a certain point in your program, you can do this:</p>
<div class="fragment"><pre class="fragment"> engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a1d37141994f73595fc96d5893844925c" title="Removes all sound sources from the engine.">removeAllSoundSources</a>();
</pre></div><p>This will remove all sounds and also cause all sounds to be stopped. To remove single sounds from the engine, use:</p>
<div class="fragment"><pre class="fragment"> engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a82e712f7816f933145690983dbd8be9e" title="Removes a sound source from the engine, freeing the memory it occupies.">removeSoundSource</a>(pointerToSomeSoundSource);
<span class="comment">// or:</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a82e712f7816f933145690983dbd8be9e" title="Removes a sound source from the engine, freeing the memory it occupies.">removeSoundSource</a>(<span class="stringliteral">&quot;nameOfASoundFile.wav&quot;</span>);
</pre></div><p>Note: Only removing buffered sounds will reduce the amount of memory used by irrKlang, streamed sounds don't occupy a lot of memory when they are not played. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="events">
Using Sound Events</a></h2>
<p>In order to wait for a sound to be finished, it is simply possible to poll <a class="el" href="classirrklang_1_1_i_sound.html#a9d9e758f8500b194580de339c7f96768" title="returns if the sound has finished playing.">irrklang::ISound::isFinished()</a>. Another way would be to constantly use <a class="el" href="classirrklang_1_1_i_sound_engine.html#a1084577f9f43cb12e86cea43c323b12c" title="Returns if a sound with the specified name is currently playing.">irrklang::ISoundEngine::isCurrentlyPlaying</a> to test wether a sound with that name or source is currently playing. But of course, an event based approach is a lot nicer. That's why irrKlang supports sound events.<br/>
The key to sound events is the method <a class="el" href="classirrklang_1_1_i_sound.html#a50dc71426d0abec7af56fa68a5bb87b5">setSoundStopEventReceiver </a> of the <a class="el" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a> interface (See <a class="el" href="index.html#changingSounds">Influencing Sounds during Playback</a> on how to get the ISound interface):</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a>* snd = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;speech.mp3&quot;</span>, <span class="keyword">false</span>, <span class="keyword">false</span>, <span class="keyword">true</span>);
<span class="keywordflow">if</span> (snd)
snd-&gt;<a class="code" href="classirrklang_1_1_i_sound.html#a50dc71426d0abec7af56fa68a5bb87b5" title="Sets the sound stop event receiver, an interface which gets called if a sound has...">setSoundStopEventReceiver</a>(yourEventReceiver, 0);
</pre></div><p>The optional second parameter of setSoundStopEventReceiver is a user pointer, set it to whatever you like. 'yourEventReceiver' must be an implementation of the <a class="el" href="classirrklang_1_1_i_sound_stop_event_receiver.html" title="Interface to be implemented by the user, which recieves sound stop events.">irrklang::ISoundStopEventReceiver</a> interface.<br/>
A whole implementation could look like this:</p>
<div class="fragment"><pre class="fragment"> <span class="keyword">class </span>MySoundEndReceiver : <span class="keyword">public</span> irrklang::ISoundStopEventReceiver
{
<span class="keyword">public</span>:
<span class="keyword">virtual</span> <span class="keywordtype">void</span> OnSoundStopped (<a class="code" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a>* sound, <a class="code" href="namespaceirrklang.html#a17ebb006afe78ab6502a1e3d18083522" title="An enumeration listing all reasons for a fired sound stop event.">irrklang::E_STOP_EVENT_CAUSE</a> reason, <span class="keywordtype">void</span>* userData)
{
<span class="comment">// called when the sound has ended playing</span>
printf(<span class="stringliteral">&quot;sound has ended&quot;</span>);
}
}
<span class="comment">// ...</span>
MySoundEndReceiver* myReceiver = <span class="keyword">new</span> MySoundEndReceiver();
<a class="code" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a>* snd = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;speech.mp3&quot;</span>, <span class="keyword">false</span>, <span class="keyword">false</span>, <span class="keyword">true</span>);
<span class="keywordflow">if</span> (snd)
snd-&gt;<a class="code" href="classirrklang_1_1_i_sound.html#a50dc71426d0abec7af56fa68a5bb87b5" title="Sets the sound stop event receiver, an interface which gets called if a sound has...">setSoundStopEventReceiver</a>(myReceiver);
myReceiver-&gt;drop(); <span class="comment">// similar to delete</span>
</pre></div><p>The <a class="el" href="classirrklang_1_1_i_sound_stop_event_receiver.html#a8e975104683b71cd45436ae5f8bfaf9f" title="Called when a sound has stopped playing.">irrklang::ISoundStopEventReceiver::OnSoundStopped()</a> method is guaranteed to be called when a sound or sound stream has stopped, either because the sound reached its playback end, its sound source was removed, ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="memoryPlayback">
Memory Playback</a></h2>
<p>Using irrKlang, it is easily possible to play sounds directly from memory instead out of files. There is an example project showing this: In the SDK, in /examples/03.MemoryPlayback. But in short, it simply works by adding the memory as sound source (See <a class="el" href="index.html#soundSources">Using Sound Sources</a> for details about sound sources):</p>
<div class="fragment"><pre class="fragment"> engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a686f6a4c8a7e90ec6859436f6ae39707" title="Adds a sound source into the sound engine as memory source.">addSoundSourceFromMemory</a>(pointerToMemory, memorySize, <span class="stringliteral">&quot;nameforthesound.wav&quot;</span>);
<span class="comment">// play sound now</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;nameforthesound.wav&quot;</span>);
</pre></div><p>Or using a sound source pointer:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1_i_sound_source.html" title="A sound source describes an input file (.ogg, .mp3, .wav or similar) and its default...">irrklang::ISoundSource</a>* snd =
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a686f6a4c8a7e90ec6859436f6ae39707" title="Adds a sound source into the sound engine as memory source.">addSoundSourceFromMemory</a>(pointerToMemory, memorySize, <span class="stringliteral">&quot;nameforthesound.wav&quot;</span>);
<span class="comment">// play sound now</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(snd);
</pre></div><p>Note: It is also possible to overwrite the file access directly, don't use this Memory Playback feature for this. See <a class="el" href="index.html#fileOverriding">Overriding File Access</a> for details. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="effects">
Sound Effects</a></h2>
<p>irrKlang supports the effects Chorus, Compressor, Distortion, Echo, Flanger Gargle, 3DL2Reverb, ParamEq and WavesReverb, when using the sound driver <a class="el" href="namespaceirrklang.html#a77f31ac02a7d33fe94807be709f72afea6fcd5ec6152066313ef04d97ea5582ee" title="DirectSound8 sound output driver, windows only.">irrklang::ESOD_DIRECT_SOUND_8</a>, which selected by default when using Windows.<br/>
</p>
<p>Using the <a class="el" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a> interface, you can optain the <a class="el" href="classirrklang_1_1_i_sound_effect_control.html" title="Interface to control the active sound effects (echo, reverb,...) of an ISound object...">irrklang::ISoundEffectControl</a> interface if the sound device supports sound effects and the last parameter ('enableSoundEffects') was set to true when calling play2D():</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classirrklang_1_1_i_sound.html" title="Represents a sound which is currently played.">irrklang::ISound</a>* snd = engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;sound.wav&quot;</span>, <span class="keyword">true</span>, <span class="keyword">false</span>, <span class="keyword">true</span>, <a class="code" href="namespaceirrklang.html#a6eab873ba387c6a4e05839e6a434d06ea9ccdf79afdb2961edf97edf4575d1717" title="Autodetects the best stream mode for a specified audio data.">ESM_AUTO_DETECT</a>, <span class="keyword">true</span>);
<span class="keywordflow">if</span> (snd)
{
<a class="code" href="classirrklang_1_1_i_sound_effect_control.html" title="Interface to control the active sound effects (echo, reverb,...) of an ISound object...">irrklang::ISoundEffectControl</a>* fx = snd-&gt;<a class="code" href="classirrklang_1_1_i_sound.html#a988bb2ccda459ad6aa3264e9a58aa99a" title="Returns the sound effect control interface for this sound.">getSoundEffectControl</a>();
<span class="keywordflow">if</span> (fx)
{
<span class="comment">// enable the echo sound effect for this sound</span>
fx-&gt;<a class="code" href="classirrklang_1_1_i_sound_effect_control.html#a5f2e867d41eb16b6e5418c1c2c92e501" title="Enables the Echo sound effect or adjusts its values.">enableEchoSoundEffect</a>();
}
}
snd-&gt;<a class="code" href="classirrklang_1_1_i_virtual_ref_counted.html#a6602c3d110f23410c5bca8a08b709aa4" title="Drops the object. Decrements the reference counter by one.">drop</a>();
</pre></div><p>This enabled the echo sound effect for this sound. The method also supports a lot of parameters, and can be called multiple times to change those parameters over time if wished. There are a lot of other sound effects, see <a class="el" href="classirrklang_1_1_i_sound_effect_control.html" title="Interface to control the active sound effects (echo, reverb,...) of an ISound object...">irrklang::ISoundEffectControl</a> for details. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="fileOverriding">
Overriding File Access</a></h2>
<p>It is possible to let irrKlang use your own file access functions. This is useful if you want to read sounds from other sources than just files, for example from custom internet streams or an own encypted archive format. There is an example in the SDK in examples/04.OverrideFileAccess which shows this as well.<br/>
</p>
<p>The only thing to do for this is to implement your own <a class="el" href="classirrklang_1_1_i_file_factory.html" title="Interface to overwrite file access in irrKlang.">irrklang::IFileFactory</a>, and set it in irrKlang using <a class="el" href="classirrklang_1_1_i_sound_engine.html#ad7c48f9d7ccc6f60adb1b3f024f9b189" title="Adds a file factory to the sound engine, making it possible to override file access...">irrklang::ISoundEngine::addFileFactory()</a>:</p>
<div class="fragment"><pre class="fragment"> <span class="comment">// a class implementing the IFileFactory interface to override irrklang file access</span>
<span class="keyword">class </span>CMyFileFactory : <span class="keyword">public</span> irrklang::IFileFactory
{
<span class="keyword">public</span>:
<span class="comment">// Opens a file for read access. Simply return 0 if file not found.</span>
<span class="keyword">virtual</span> <a class="code" href="classirrklang_1_1_i_file_reader.html" title="Interface providing read acess to a file.">irrklang::IFileReader</a>* createFileReader(<span class="keyword">const</span> <a class="code" href="namespaceirrklang.html#af179ad966eb79d01f6d1cf8927087449" title="8 bit character variable.">ik_c8</a>* filename)
{
<span class="comment">// return your own irrklang::IFileReader implementation here, for example like that:</span>
<span class="keywordflow">return</span> <span class="keyword">new</span> CMyReadFile(filename);
}
};
<span class="comment">// ...</span>
CMyFileFactory* myFactory = <span class="keyword">new</span> CMyFileFactory();
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#ad7c48f9d7ccc6f60adb1b3f024f9b189" title="Adds a file factory to the sound engine, making it possible to override file access...">addFileFactory</a>(myFactory);
myFactory-&gt;drop();
</pre></div><p>For a full example implementation, just take a look into the SDK in examples/04.OverrideFileAccess. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="audioDecoders">
Adding Audio Decoders</a></h2>
<p>To add support for new file formats, it is possible to add new audio decoders to irrKlang. The only thing to do for this is to implement your own <a class="el" href="classirrklang_1_1_i_audio_stream_loader.html" title="Class which is able to create an audio file stream from a file.">irrklang::IAudioStreamLoader</a>, and <a class="el" href="classirrklang_1_1_i_audio_stream.html" title="Reads and decodes audio data into an usable audio stream for the ISoundEngine.">irrklang::IAudioStream</a>, and set it in irrKlang using <a class="el" href="classirrklang_1_1_i_sound_engine.html#a6cb64f878a5355454c7197276127a7c9" title="Registers a new audio stream loader in the sound engine.">irrklang::ISoundEngine::registerAudioStreamLoader()</a>:</p>
<div class="fragment"><pre class="fragment"> <span class="keyword">class </span>NewAudioStreamLoader : <span class="keyword">public</span> irrklang::IAudioStreamLoader
{
<span class="comment">// ... returns NewAudioDecoder and the used file name suffices.</span>
};
<span class="keyword">class </span>NewAudioDecoder : <span class="keyword">public</span> irrklang::IAudioStream
{
<span class="keyword">public</span>:
<span class="comment">// ... decodes the new file format</span>
};
<span class="comment">// ...</span>
NewAudioDecoder* loader = <span class="keyword">new</span> NewAudioDecoder();
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a6cb64f878a5355454c7197276127a7c9" title="Registers a new audio stream loader in the sound engine.">registerAudioStreamLoader</a>(loader);
loader-&gt;drop();
</pre></div><p>There is an example audio decoder and loader with full source in plugins/ikpMP3, which adds MP3 audio decoding capabilities to irrKlang. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="plugins">
Creating irrKlang Plugins</a></h2>
<p>irrKlang plugins are ikp*.dll (Windows), ikp*.so (Unix) or ikp*.dylib (MacOS) files which are loaded by irrKlang at startup when the <a class="el" href="namespaceirrklang.html#ac9155ff55b347df6e905462100762d7fafda608a17564b562a9a43b7934a387e8" title="Automaticly loads external plugins when starting up.">irrklang::ESEO_LOAD_PLUGINS</a> was set (which is default) or <a class="el" href="classirrklang_1_1_i_sound_engine.html#abcb159bed86265a22fe3435ce2541ea6" title="Loads irrKlang plugins from a custom path.">irrklang::ISoundEngine::loadPlugins()</a> was called. <br/>
</p>
<p>The plugin only needs to contain the following function which will be called by irrKlang:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #ifdef WIN32</span>
<span class="preprocessor"></span> <span class="comment">// Windows version</span>
__declspec(dllexport) void __stdcall irrKlangPluginInit(ISoundEngine* engine, const <span class="keywordtype">char</span>* version)
<span class="preprocessor">#else</span>
<span class="preprocessor"></span> <span class="comment">// Linux and Mac OS version</span>
<span class="keywordtype">void</span> irrKlangPluginInit(ISoundEngine* engine, <span class="keyword">const</span> <span class="keywordtype">char</span>* version)
<span class="preprocessor">#endif</span>
<span class="preprocessor"></span> {
<span class="comment">// your implementation here</span>
}
</pre></div><p>In there, it is for example possible to extend irrKlang with new audio decoders, see <a class="el" href="index.html#audioDecoders">Adding Audio Decoders</a> for details. <br/>
</p>
<p>There is an example plugin with full source in plugins/ikpMP3, which adds MP3 audio decoding capabilities to irrKlang. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="staticLib">
Using irrKlang as static Lib</a></h2>
<p>If you don't want to use the irrKlang.DLL file and link irrKlang statically, you can do this by simply linking to the irrKlang.lib in the bin/win32-visualstudio_lib folder. This folder will only available in the pro versions of irrKlang, which you get when purchasing an irrKlang license.</p>
<p>To use irrKlang in this way, just define IRRKLANG_STATIC before including <a class="el" href="irr_klang_8h.html" title="Main header file of the irrKlang sound library, the only file needed to include.">irrklang.h</a>, like this:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #define IRRKLANG_STATIC</span>
<span class="preprocessor"> #include &lt;irrKlang.h&gt;</span>
</pre></div><p>Of course, IRRKLANG_STATIC can also simply be defined in the project/compiler settings instead of in the source file. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="enumeratingDevices">
Enumerating sound devices</a></h2>
<p>irrKlang uses the default sound device when playing sound when started without parameters. But if you want irrKlang to playback sound on one specific sound device, you may want to enumerate the available sound devices on your system and select one of them. Use <a class="el" href="namespaceirrklang.html#a38d9a69bf54fd60e76e80e199e44faee" title="Creates a list of available sound devices for the driver type.">irrklang::createSoundDeviceList()</a> for this. This example code shows how to print a list of all available sound devices on the current system and lets the user choose one of them:</p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keyword">const</span> <span class="keywordtype">char</span>** argv)
{
<span class="comment">// enumerate devices</span>
<a class="code" href="classirrklang_1_1_i_sound_device_list.html" title="A list of sound devices for a sound driver. Use irrklang::createSoundDeviceList()...">irrklang::ISoundDeviceList</a>* deviceList = <a class="code" href="namespaceirrklang.html#a38d9a69bf54fd60e76e80e199e44faee" title="Creates a list of available sound devices for the driver type.">createSoundDeviceList</a>();
<span class="comment">// ask user for a sound device</span>
printf(<span class="stringliteral">&quot;Devices available:\n\n&quot;</span>);
<span class="keywordflow">for</span> (<span class="keywordtype">int</span> i=0; i&lt;deviceList-&gt;<a class="code" href="classirrklang_1_1_i_sound_device_list.html#a546d93bf5e70b5b168c430329194f2e4" title="Returns amount of enumerated devices in the list.">getDeviceCount</a>(); ++i)
printf(<span class="stringliteral">&quot;%d: %s\n&quot;</span>, i, deviceList-&gt;<a class="code" href="classirrklang_1_1_i_sound_device_list.html#a79160c5136dbdcd81999f3d95d603498" title="Returns description of the device.">getDeviceDescription</a>(i));
printf(<span class="stringliteral">&quot;\nselect a device using the number (or press any key to use default):\n\n&quot;</span>);
<span class="keywordtype">int</span> deviceNumber = getch() - <span class="charliteral">&apos;0&apos;</span>;
<span class="comment">// create device with the selected driver</span>
<span class="keyword">const</span> <span class="keywordtype">char</span>* deviceID = deviceList-&gt;<a class="code" href="classirrklang_1_1_i_sound_device_list.html#a77509686d507ea5939a50d31ca8fdf93" title="Returns the ID of the device. Use this string to identify this device in createIrrKlangDevice()...">getDeviceID</a>(deviceNumber);
ISoundEngine* engine = <a class="code" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">createIrrKlangDevice</a>(<a class="code" href="namespaceirrklang.html#a77f31ac02a7d33fe94807be709f72afea8cc9863f3b410698313b8637721e51ec" title="Autodetects the best sound driver for the system.">irrklang::ESOD_AUTO_DETECT</a>,
<a class="code" href="namespaceirrklang.html#ac9155ff55b347df6e905462100762d7facca58ad3ee7e3c2e874bc4015f36f2a9" title="Default parameters when starting up the engine.">irrklang::ESEO_DEFAULT_OPTIONS</a>,
deviceID);
deviceList-&gt;<a class="code" href="classirrklang_1_1_i_ref_counted.html#a869fe3adc6e49e8da105e95837a565b1">drop</a>(); <span class="comment">// delete device list</span>
<span class="comment">// ... use engine now</span>
}
</pre></div><p>In this way, it is also possible to play back sound using two devices at the same time: Simply create two irrKlang devices with each a different deviceID.<br/>
Note: <a class="el" href="namespaceirrklang.html#a38d9a69bf54fd60e76e80e199e44faee" title="Creates a list of available sound devices for the driver type.">createSoundDeviceList()</a> takes a driver type parameter (such as irrklang::ESOD_DIRECT_SOUND8), which you have to set to the same value as the first parameter you want to use with <a class="el" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">createIrrKlangDevice()</a>, if it is other than <a class="el" href="namespaceirrklang.html#a77f31ac02a7d33fe94807be709f72afea8cc9863f3b410698313b8637721e51ec" title="Autodetects the best sound driver for the system.">irrklang::ESOD_AUTO_DETECT</a>. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="recordingAudio">
Recording Audio</a></h2>
<p>irrKlang is able to record audio from sound capturing devices such as microphones (currently only supported in windows). Use the <a class="el" href="classirrklang_1_1_i_audio_recorder.html" title="Interface to an audio recorder. Create it using the createIrrKlangAudioRecorder()...">irrklang::IAudioRecorder</a> interface to do this. The following example shows how to record some audio and play it back again using the engine:</p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keyword">const</span> <span class="keywordtype">char</span>** argv)
{
<a class="code" href="classirrklang_1_1_i_sound_engine.html" title="Interface to the sound engine, for playing 3d and 2d sound and music.">irrklang::ISoundEngine</a>* engine = <a class="code" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">irrklang::createIrrKlangDevice</a>();
<a class="code" href="classirrklang_1_1_i_audio_recorder.html" title="Interface to an audio recorder. Create it using the createIrrKlangAudioRecorder()...">irrklang::IAudioRecorder</a>* recorder = <a class="code" href="namespaceirrklang.html#aaa4535359bd66857aaadb746cf7d8cec" title="Creates an irrKlang audio recording device. The IAudioRecorder is the root object...">irrklang::createIrrKlangAudioRecorder</a>(engine);
<span class="keywordflow">if</span> (!engine || !recorder)
{
printf(<span class="stringliteral">&quot;Could not create audio engine or audio recoder\n&quot;</span>);
<span class="keywordflow">return</span> 1;
}
printf(<span class="stringliteral">&quot;\nPress any key to start recording audio...\n&quot;</span>);
getch();
<span class="comment">// record some audio</span>
recorder-&gt;<a class="code" href="classirrklang_1_1_i_audio_recorder.html#ad02c63bf445c6f916e43271c428a05f4" title="Starts recording audio.">startRecordingBufferedAudio</a>();
printf(<span class="stringliteral">&quot;\nRECORDING. Press any key to stop...\n&quot;</span>);
getch();
recorder-&gt;<a class="code" href="classirrklang_1_1_i_audio_recorder.html#aa00ecf279dfad147e313acac7a04024b" title="Stops recording audio.">stopRecordingAudio</a>();
printf(<span class="stringliteral">&quot;\nRecording done, recorded %dms of audio.\n&quot;</span>,
recorder-&gt;<a class="code" href="classirrklang_1_1_i_audio_recorder.html#ac6f664694d15960dff90d9288850c472" title="Returns the audio format of the recorded audio data.">getAudioFormat</a>().FrameCount * 1000 / recorder-&gt;<a class="code" href="classirrklang_1_1_i_audio_recorder.html#ac6f664694d15960dff90d9288850c472" title="Returns the audio format of the recorded audio data.">getAudioFormat</a>().SampleRate );
printf(<span class="stringliteral">&quot;Press any key to play back recorded audio...\n&quot;</span>);
getch();
<span class="comment">// play the recorded audio</span>
recorder-&gt;<a class="code" href="classirrklang_1_1_i_audio_recorder.html#ab70d79f62eadea7bd54e3730105b14d6" title="Creates a sound source for the recorded audio data.">addSoundSourceFromRecordedAudio</a>(<span class="stringliteral">&quot;myRecordedVoice&quot;</span>);
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;myRecordedVoice&quot;</span>, <span class="keyword">true</span>);
<span class="comment">// wait until user presses a key</span>
printf(<span class="stringliteral">&quot;\nPress any key to quit...&quot;</span>);
getch();
recorder-&gt;<a class="code" href="classirrklang_1_1_i_ref_counted.html#a869fe3adc6e49e8da105e95837a565b1">drop</a>();
engine-&gt;<a class="code" href="classirrklang_1_1_i_ref_counted.html#a869fe3adc6e49e8da105e95837a565b1">drop</a>(); <span class="comment">// delete engine</span>
<span class="keywordflow">return</span> 0;
}
</pre></div><p>In order to select a specific audio capturing device for recording, it is necessary to enumerate the available devices. Simply replace the first to lines of code of the example above with code like this to list all devices and select one:</p>
<div class="fragment"><pre class="fragment"> <span class="comment">// enumerate recording devices and ask user to select one</span>
<a class="code" href="classirrklang_1_1_i_sound_device_list.html" title="A list of sound devices for a sound driver. Use irrklang::createSoundDeviceList()...">irrklang::ISoundDeviceList</a>* deviceList = <a class="code" href="namespaceirrklang.html#a0e8013b9e8f11231e69ce1da9457a339" title="Creates a list of available recording devices for the driver type.">irrklang::createAudioRecorderDeviceList</a>();
printf(<span class="stringliteral">&quot;Devices available:\n\n&quot;</span>);
<span class="keywordflow">for</span> (<span class="keywordtype">int</span> i=0; i&lt;deviceList-&gt;<a class="code" href="classirrklang_1_1_i_sound_device_list.html#a546d93bf5e70b5b168c430329194f2e4" title="Returns amount of enumerated devices in the list.">getDeviceCount</a>(); ++i)
printf(<span class="stringliteral">&quot;%d: %s\n&quot;</span>, i, deviceList-&gt;<a class="code" href="classirrklang_1_1_i_sound_device_list.html#a79160c5136dbdcd81999f3d95d603498" title="Returns description of the device.">getDeviceDescription</a>(i));
printf(<span class="stringliteral">&quot;\nselect a device using the number (or press any key to use default):\n\n&quot;</span>);
<span class="keywordtype">int</span> deviceNumber = getch() - <span class="charliteral">&apos;0&apos;</span>;
<span class="comment">// create recording device with the selected driver</span>
<span class="keyword">const</span> <span class="keywordtype">char</span>* deviceID = deviceList-&gt;<a class="code" href="classirrklang_1_1_i_sound_device_list.html#a77509686d507ea5939a50d31ca8fdf93" title="Returns the ID of the device. Use this string to identify this device in createIrrKlangDevice()...">getDeviceID</a>(deviceNumber);
<a class="code" href="classirrklang_1_1_i_sound_engine.html" title="Interface to the sound engine, for playing 3d and 2d sound and music.">irrklang::ISoundEngine</a>* engine = <a class="code" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">irrklang::createIrrKlangDevice</a>();
<a class="code" href="classirrklang_1_1_i_audio_recorder.html" title="Interface to an audio recorder. Create it using the createIrrKlangAudioRecorder()...">irrklang::IAudioRecorder</a>* recorder =
<a class="code" href="namespaceirrklang.html#aaa4535359bd66857aaadb746cf7d8cec" title="Creates an irrKlang audio recording device. The IAudioRecorder is the root object...">irrklang::createIrrKlangAudioRecorder</a>(engine, <a class="code" href="namespaceirrklang.html#a77f31ac02a7d33fe94807be709f72afea8cc9863f3b410698313b8637721e51ec" title="Autodetects the best sound driver for the system.">irrklang::ESOD_AUTO_DETECT</a>, deviceID);
</pre></div><p><br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="unicode">
Unicode support</a></h2>
<p>irrKlang supports unicode on all operating systems. Internally, it uses UTF8, and all functions accepting strings and file names take UTF8 strings. If you are running irrKlang on Windows, and are using the UNICODE define or using wchar_t* strings directly, you can do this as well. Use the irrKlang provided function <a class="el" href="namespaceirrklang.html#a2552f41aac247b77e0f1287c28744cd7" title="Converts a wchar_t string to an utf8 string, useful when using Windows in unicode...">makeUTF8fromUTF16string()</a> to convert your wchar_t* string to a char* string.</p>
<p>This example shows how:</p>
<div class="fragment"><pre class="fragment"> <span class="keyword">const</span> <span class="keywordtype">wchar_t</span>* yourFilename = L<span class="stringliteral">&quot;SomeUnicodeFilename.wav&quot;</span>; <span class="comment">// assuming this is the file name you get from some of your functions</span>
<span class="keyword">const</span> <span class="keywordtype">int</span> nBufferSize = 2048; <span class="comment">// large enough, but best would be wcslen(yourFilename)*3.</span>
<span class="keywordtype">char</span> strBuffer[nBufferSize];
<a class="code" href="namespaceirrklang.html#a2552f41aac247b77e0f1287c28744cd7" title="Converts a wchar_t string to an utf8 string, useful when using Windows in unicode...">irrklang::makeUTF8fromUTF16string</a>(yourFilename, strBuffer, nBufferSize);
<span class="comment">// now the converted file name is in strBuffer. We can play it for example now:</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(strBuffer);
</pre></div><p>Of course, you can use any other unicode converion function for this. <a class="el" href="namespaceirrklang.html#a2552f41aac247b77e0f1287c28744cd7" title="Converts a wchar_t string to an utf8 string, useful when using Windows in unicode...">makeUTF8fromUTF16string()</a> is only provided for convenience. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="quickstartexample">
Quick Start Example</a></h2>
<p>To simply start the engine and play a mp3 file, use code like this:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;iostream&gt;</span>
<span class="preprocessor"> #include &lt;<a class="code" href="irr_klang_8h.html" title="Main header file of the irrKlang sound library, the only file needed to include.">irrKlang.h</a>&gt;</span>
<span class="preprocessor"> #pragma comment(lib, &quot;irrKlang.lib&quot;) // link with irrKlang.dll</span>
<span class="preprocessor"></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keyword">const</span> <span class="keywordtype">char</span>** argv)
{
<a class="code" href="classirrklang_1_1_i_sound_engine.html" title="Interface to the sound engine, for playing 3d and 2d sound and music.">irrklang::ISoundEngine</a>* engine = <a class="code" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">irrklang::createIrrKlangDevice</a>();
<span class="keywordflow">if</span> (!engine) <span class="keywordflow">return</span> 1; <span class="comment">// could not start engine</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_sound_engine.html#a25f612fe6479d3b22dc5bab2a2eaa927" title="loads a sound source (if not loaded already) from a file and plays it.">play2D</a>(<span class="stringliteral">&quot;someMusic.mp3&quot;</span>, <span class="keyword">true</span>); <span class="comment">// play some mp3 file, looped</span>
std::cin.get(); <span class="comment">// wait until user presses a key</span>
engine-&gt;<a class="code" href="classirrklang_1_1_i_ref_counted.html#a869fe3adc6e49e8da105e95837a565b1">drop</a>(); <span class="comment">// delete engine</span>
<span class="keywordflow">return</span> 0;
}
</pre></div><p>A mp3 file is being played until the user presses enter in this example. As you can see, irrKlang uses <a href="namespaces.html">namespaces</a>, all of the classes are located in the namespace <a class="el" href="namespaceirrklang.html" title="Everything in the irrKlang Sound Engine can be found in this namespace.">irrklang</a>. If you don't want to write this in front of every class and function you are using, simply write</p>
<div class="fragment"><pre class="fragment"> <span class="keyword">using namespace </span>irrklang;
</pre></div><p> in front of your code, as also shown in the next example. <br/>
<br/>
<br/>
<br/>
</p>
<h2><a class="anchor" id="quickstartexample2">
Quick Start Example 2</a></h2>
<p>The following is a simple interactive application, starting up the sound engine and playing some streaming .ogg music file and a .wav sound effect every time the user presses a key.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;iostream&gt;</span>
<span class="preprocessor"> #include &lt;<a class="code" href="irr_klang_8h.html" title="Main header file of the irrKlang sound library, the only file needed to include.">irrKlang.h</a>&gt;</span>
<span class="keyword">using namespace </span>irrklang;
<span class="preprocessor"> #pragma comment(lib, &quot;irrKlang.lib&quot;) // link with irrKlang.dll</span>
<span class="preprocessor"></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keyword">const</span> <span class="keywordtype">char</span>** argv)
{
<span class="comment">// start the sound engine with default parameters</span>
ISoundEngine* engine = <a class="code" href="namespaceirrklang.html#ad9829f898bc0665fdd2554a6f5c7ca1c" title="Creates an irrKlang device. The irrKlang device is the root object for using the...">createIrrKlangDevice</a>();
<span class="keywordflow">if</span> (!engine)
<span class="keywordflow">return</span> 0; <span class="comment">// error starting up the engine</span>
<span class="comment">// play some sound stream, looped</span>
engine-&gt;play2D(<span class="stringliteral">&quot;../../media/helltroopers.ogg&quot;</span>, <span class="keyword">true</span>);
std::cout &lt;&lt; <span class="stringliteral">&quot;\nHello World!\n&quot;</span>;
<span class="keywordtype">char</span> i = 0;
<span class="keywordflow">while</span>(i != <span class="charliteral">&apos;q&apos;</span>)
{
std::cout &lt;&lt; <span class="stringliteral">&quot;Press any key to play some sound, press &apos;q&apos; to quit.\n&quot;</span>;
<span class="comment">// play a single sound</span>
engine-&gt;play2D(<span class="stringliteral">&quot;../../media/bell.wav&quot;</span>);
std::cin &gt;&gt; i; <span class="comment">// wait for user to press some key</span>
}
engine-&gt;drop(); <span class="comment">// delete engine</span>
<span class="keywordflow">return</span> 0;
}
</pre></div> </div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&nbsp;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&nbsp;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&nbsp;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&nbsp;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&nbsp;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&nbsp;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&nbsp;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&nbsp;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&nbsp;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&nbsp;</span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr size="1">
<address style="align: right;">
<small> </small>
</address>
<table width="100%" border="0" cellspacing="0" cellpadding="2">
<tr>
<td width="0"> <div align="left"><small><a href="http://www.ambiera.com/irrklang" target="_blank"><img src="irrklang.png" alt="irrKlang Audio Library" align="middle" border=0 width=88 height=30></a></small></div></td>
<td> <div align="left"><small><em><font size="2">The <a href="http://www.ambiera.com/irrklang" target="_blank">irrKlang
Engine</a> Documentation &copy; 2003-2018 by Nikolaus Gebhardt. Generated
by <a href="http://www.doxygen.org" target="_blank">Doxygen</a>
(1.6.1)</font></em></small></div></td>
</tr>
</table>
<address style="align: right;">
</address>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink