irrKlang.h

/* irrKlang.h -- interface of the 'irrKlang' library

  Copyright (C) 2002-2018 Nikolaus Gebhardt

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.
*/

#ifndef __IRR_KLANG_H_INCLUDED__
#define __IRR_KLANG_H_INCLUDED__

#include "ik_irrKlangTypes.h"
#include "ik_vec3d.h"

#include "ik_IRefCounted.h"
#include "ik_IVirtualRefCounted.h"

#include "ik_ESoundOutputDrivers.h"
#include "ik_ESoundEngineOptions.h"
#include "ik_EStreamModes.h"
#include "ik_SAudioStreamFormat.h"
#include "ik_ISoundEngine.h"
#include "ik_ISoundSource.h"
#include "ik_ISound.h"
#include "ik_IAudioStream.h"
#include "ik_IAudioStreamLoader.h"
#include "ik_ISoundEffectControl.h"
#include "ik_ISoundStopEventReceiver.h"
#include "ik_IFileFactory.h"
#include "ik_IFileReader.h"
#include "ik_ISoundDeviceList.h"
#include "ik_IAudioRecorder.h"
#include "ik_ISoundMixedOutputReceiver.h"

//! irrKlang Version
#define IRR_KLANG_VERSION "1.6.0"

/*! \mainpage irrKlang 1.6.0 API documentation
 *
 * <div align="center"><img src="logobig.png" ></div>

 * \section contents Contents
 * General:<br/>
 * @ref intro <br/>
 * @ref features <br/>
 * @ref links <br/>
 * @ref tipsandtricks <br/>
 * <br/>
 * Programming irrKlang:<br/>
 * @ref concept <br/>
 * @ref playingSounds <br/>
 * @ref changingSounds <br/>
 * @ref soundSources <br/>
 * @ref sound3d <br/>
 * @ref removingSounds <br/>
 * @ref events <br/>
 * @ref memoryPlayback <br/>
 * @ref effects <br/>
 * @ref fileOverriding <br/>
 * @ref audioDecoders <br/>
 * @ref plugins <br/>
 * @ref staticLib <br/>
 * @ref enumeratingDevices <br/>
 * @ref recordingAudio <br/>
 * @ref unicode <br/>
 * <br/>
 * Short full examples:<br/>
 * @ref quickstartexample <br/>
 * @ref quickstartexample2 <br/>
 * <br/>
 * <br/>
 *
 * \section intro Introduction
 *
 * 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 \examples.
 *
 * 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.
 *
 * <br/>
 * <br/>
 *
 *
 * \section features Features of irrKlang
 *
 * 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
 * <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>
 * It is also able to run on different operating systems and use several output drivers:
 *<ul>
 *       <li>Windows 98, ME, NT 4, 2000, XP, Vista, Windows 7, Windows 8</li>
 *	<ul>
 *       <li>DirectSound</li>
 *       <li>DirectSound8</li>
 *       <li>WinMM</li>
 *	</ul>
 *       <li>Linux / *nix</li>	
 *	<ul>
 *       <li>ALSA</li>
 *	</ul>
 *  <li>MacOSX (x86 and PPC)</li>
 *	<ul>
 *       <li>CoreAudio</li>
 *	</ul>
 * </ul>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section links Links into the API documentation
 *
 * irrklang::ISoundEngine: 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/>
 *
 *
 *
  * \section tipsandtricks Tips and Tricks
 *
 * This section lists a few tips you might consider when implementing the sound part of your application
 * using irrKlang:
 *
 * <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 irrklang::IRefCounted::drop(). Be sure you are doing it correctly. (If you are unsure,
 *                   tempoarily remove all calls to irrklang::IRefCounted::drop() and see if this helps.)</li>
 * </ul>
 *
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section concept Starting up the Engine
 *
 * irrKlang is designed so that it is very easy to achieve everything, its interface should
 * be very simple to use. The @ref quickstartexample shows how to play and mp3 file, and there
 * is another example, @ref quickstartexample2, showing some few more details.<br/>
 * To start up the sound engine, you simply need to call createIrrKlangDevice(). To shut it down,
 * call IRefCounted::drop():
 *
 * \code
 * #include <irrKlang.h>
 *
 * // ...
 *
 * // start up the engine
 * irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice();
 *	
 * // ...
 * 
 * // after finished,
 * // close the engine again, similar as calling 'delete'
 * engine->drop(); 
 * \endcode
 *
 * The createIrrKlangDevice() 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/>
 *
 *
 *
 * \section playingSounds Playing Sounds
 *
 * Once you have irrKlang running (like in @ref concept), you can start playing sounds:
 *
 * \code
 * engine->play2D("someSoundFile.wav"); 
 * \endcode
 *
 * 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':
 *
 * \code
 * engine->play2D("myMusic.mp3", true); 
 * \endcode 
 *
 * To stop this looping sound again, use engine->\link irrklang::ISoundEngine::stopAllSounds stopAllSounds()\endlink to stop all sounds, or
 * irrklang::ISound::stop() if you only want to stop that single sound. @ref changingSounds
 * shows how to get to that ISound interface.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 * \section changingSounds Influencing Sounds during Playback
 * 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 irrklang::ISound interface. 
 * irrklang::ISoundEngine::play2D (but also play3D) returns
 * a pointer to this interface when its third ('startPaused') or fourth ('track') parameter
 * was set to true:
 *
 * \code
 * irrklang::ISound* snd = engine->play2D("myMusic.mp3", true, false, true); 
 *
 * // ...
 *
 * if (snd)
 *     snd->setVolume(someNewValue);
 * 
 * // ...
 * 
 * if (snd)
 * {
 *     snd->drop(); // don't forget to release the pointer once it is no longer needed by you
 *     snd = 0;
 * }
 * \endcode
 *
 * The irrklang::ISound 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/>
 *
 *
 * \section soundSources Using Sound Sources
 *
 * 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:
 *
 * \code
 * irrklang::ISoundSource* shootSound = engine->addSoundSourceFromFile("shoot.wav"); 
 *
 * engine->play2D(shootSound);
 *
 * // note: you don't need to drop() the shootSound if you don't use it anymore
 * \endcode
 *
 * The advantage of using irrklang::ISoundSource 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:
 *
 * \code
 * irrklang::ISoundSource* shootSound = engine->addSoundSourceFromFile("shoot.wav"); 
 *
 * shootSound->setDefaultVolume(0.5f);
 *
 * // shootSound will now be played with half its sound volume by default:
 * engine->play2D(shootSound);
 * \endcode
 *
 * It is also possible to have multiple settings for the same sound file:
 *
 * \code
 * irrklang::ISoundSource* shootSound = engine->addSoundSourceFromFile("shoot.wav"); 
 * irrklang::ISoundSource* shootSound2 = engine->addSoundSourceAlias(shootSound, "silentShoot"); 
 *
 * shootSound2->setDefaultVolume(0.1f);
 *
 * // shootSound will now be played with 100% of its sound volume by default,
 * // shootSound2 will now be played 10% of its sound volume by default. It is 
 * //  also possible to play it using engine->play("silentShoot"), now.
 * \endcode
 *
 * 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 irrklang::ISound, 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/>
 *
 *
 *
 * \section sound3d 3D Sound
 *
 * There is nothing difficult in playing sounds in 3D using irrKlang: Instead of using 
 * irrklang::ISoundEngine::play2D(), just use irrklang::ISoundEngine::play3D(), which
 * takes a 3D position as additional parameter:
 *
 * \code
 * irrklang::vec3df position(23,70,90);
 * engine->play3D("yourSound.wav", position);
 * \endcode
 *
 * 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 @ref soundSources) or set these values after you have started the sound paused:
 *
 * \code
 * irrklang::vec3df position(23,70,90);
 *
 * // start the sound paused:
 * irrklang::ISound* snd = engine->play3D("yourSound.wav", position, false, true);
 *
 * if (snd)
 * {
 *    snd->setMinDistance(30.0f); // a loud sound
 *    snd->setIsPaused(false); // unpause the sound
 * }
 * \endcode
 * 
 * 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:
 * 
 * \code
 * if (snd)
 *    snd->setPosition(newPosition);
 * \endcode
 *
 * 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:
 * 
 * \code
 * if (snd)
 * {
 *    snd->drop();
 *    snd = 0;
 * }
 * \endcode
 *
 * To update the position of yourself, the listener of the 3D sounds, use this from
 * time to time:
 *
 * \code
 * irrklang::vec3df position(0,0,0);        // position of the listener
 * irrklang::vec3df lookDirection(10,0,10); // the direction the listener looks into
 * irrklang::vec3df velPerSecond(0,0,0);    // only relevant for doppler effects
 * irrklang::vec3df upVector(0,1,0);        // where 'up' is in your 3D scene
 *
 * engine->setListenerPosition(position, lookDirection, velPerSecond, upVector);
 * \endcode
 *
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 * \section removingSounds Removing Sounds
 *
 * 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:
 *
 * \code
 * engine->removeAllSoundSources(); 
 * \endcode
 *
 * This will remove all sounds and also cause all sounds to be stopped. To remove single
 * sounds from the engine, use:
 *
 * \code
 * engine->removeSoundSource(pointerToSomeSoundSource); 
 * // or:
 * engine->removeSoundSource("nameOfASoundFile.wav"); 
 * \endcode
 *
 * 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/>
 *
 *
 *
 * \section events Using Sound Events
 *
 * In order to wait for a sound to be finished, it is simply possible to 
 * poll irrklang::ISound::isFinished(). Another way would be to constantly use 
 * irrklang::ISoundEngine::isCurrentlyPlaying 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 
 * \link irrklang::ISound::setSoundStopEventReceiver setSoundStopEventReceiver \endlink
 * of the irrklang::ISound interface
 * (See @ref changingSounds on how to get the ISound interface):
 *
 * \code
 * irrklang::ISound* snd = engine->play2D("speech.mp3", false, false, true); 
 * if (snd)
 *    snd->setSoundStopEventReceiver(yourEventReceiver, 0);
 * \endcode
 * 
 * The optional second parameter of setSoundStopEventReceiver is a user pointer, set it to whatever you like.
 * 'yourEventReceiver' must be an implementation of the irrklang::ISoundStopEventReceiver interface.<br/>
 * A whole implementation could look like this:
 *
 * \code
 * class MySoundEndReceiver : public irrklang::ISoundStopEventReceiver
 * {
 *   public:
 *     virtual void OnSoundStopped (irrklang::ISound* sound, irrklang::E_STOP_EVENT_CAUSE reason, void* userData)
 *     {
 *        // called when the sound has ended playing
 *        printf("sound has ended");
 *     }
 * }
 *
 * // ...
 *
 * MySoundEndReceiver* myReceiver = new MySoundEndReceiver();
 * irrklang::ISound* snd = engine->play2D("speech.mp3", false, false, true); 
 * if (snd)
 *    snd->setSoundStopEventReceiver(myReceiver);
 *
 * myReceiver->drop(); // similar to delete
 * \endcode
 * 
 * The irrklang::ISoundStopEventReceiver::OnSoundStopped() 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/>
 *
 *
 *
 * \section memoryPlayback Memory Playback
 *
 * 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 @ref soundSources for 
 * details about sound sources):
 *
 * \code
 * engine->addSoundSourceFromMemory(pointerToMemory, memorySize, "nameforthesound.wav");
 * 
 * // play sound now
 * engine->play2D("nameforthesound.wav");
 * \endcode
 *
 * Or using a sound source pointer:
 *
 * \code
 * irrklang::ISoundSource* snd = 
 *   engine->addSoundSourceFromMemory(pointerToMemory, memorySize, "nameforthesound.wav");
 * 
 * // play sound now
 * engine->play2D(snd);
 * \endcode
 *
 * Note: It is also possible to overwrite the file access directly, don't use this Memory Playback
 * feature for this. See @ref fileOverriding for details.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section effects Sound Effects
 *
 * irrKlang supports the effects Chorus, Compressor, Distortion, Echo, Flanger
 * Gargle, 3DL2Reverb, ParamEq and WavesReverb, when using the sound driver 
 * irrklang::ESOD_DIRECT_SOUND_8, which selected by default when using Windows.<br/>
 *
 * Using the irrklang::ISound interface, you can optain the irrklang::ISoundEffectControl
 * interface if the sound device supports sound effects and the last parameter ('enableSoundEffects')
 * was set to true when calling play2D():
 *
 * \code
 * irrklang::ISound* snd = engine->play2D("sound.wav", true, false, true, ESM_AUTO_DETECT, true);
 *
 * if (snd)
 * {
 *    irrklang::ISoundEffectControl* fx = snd->getSoundEffectControl();
 *    if (fx)
 *    {
 *        // enable the echo sound effect for this sound
 *        fx->enableEchoSoundEffect();
 *    }
 * }
 * 
 * snd->drop();
 * \endcode
 *
 * 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 irrklang::ISoundEffectControl for details.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section fileOverriding Overriding File Access
 *
 * 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/>
 *
 * The only thing to do for this is to implement your own  irrklang::IFileFactory,
 * and set it in irrKlang using irrklang::ISoundEngine::addFileFactory():
 *
 * \code
 * // a class implementing the IFileFactory interface to override irrklang file access
 * class CMyFileFactory : public irrklang::IFileFactory
 * {
 *   public:
 *
 *   // Opens a file for read access. Simply return 0 if file not found.
 *   virtual irrklang::IFileReader* createFileReader(const ik_c8* filename)
 *   {
 *     // return your own irrklang::IFileReader implementation here, for example like that:
 *     return new CMyReadFile(filename);
 *   }
 * };
 * 
 * // ...
 *
 * CMyFileFactory* myFactory = new CMyFileFactory();
 * engine->addFileFactory(myFactory);
 * myFactory->drop();
 * \endcode
 *
 * For a full example implementation, just take a look into the SDK in examples/04.OverrideFileAccess.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section audioDecoders Adding Audio Decoders
 *
 * 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  irrklang::IAudioStreamLoader,
 * and irrklang::IAudioStream, and set it in irrKlang using 
 * irrklang::ISoundEngine::registerAudioStreamLoader():
 *
 * \code
 * class NewAudioStreamLoader : public irrklang::IAudioStreamLoader
 * {
 *   // ... returns NewAudioDecoder and the used file name suffices.
 * };
 *
 * class NewAudioDecoder : public irrklang::IAudioStream
 * {
 *   public:
 *     // ... decodes the new file format
 * };
 *
 * // ...
 *
 * NewAudioDecoder* loader = new NewAudioDecoder();
 * engine->registerAudioStreamLoader(loader);
 * loader->drop();
 * \endcode
 * 
 * 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/>
 *
 *
 *
 * \section plugins Creating irrKlang Plugins
 *
 * irrKlang plugins are ikp*.dll (Windows), ikp*.so (Unix) or ikp*.dylib (MacOS) 
 * files which are loaded by irrKlang at startup when the 
 * irrklang::ESEO_LOAD_PLUGINS was set (which is default) or
 * irrklang::ISoundEngine::loadPlugins() was called. <br/>
 *
 * The plugin only needs to contain the following function which will be called by irrKlang:
 *
 * \code
 * #ifdef WIN32
 * // Windows version
 * __declspec(dllexport) void __stdcall irrKlangPluginInit(ISoundEngine* engine, const char* version)
 * #else
 * // Linux and Mac OS version
 * void irrKlangPluginInit(ISoundEngine* engine, const char* version)
 * #endif
 * {
 *   // your implementation here
 * }
 * \endcode
 *
 * In there, it is for example possible to extend irrKlang with new audio decoders,
 * see @ref audioDecoders for details. <br/>
 * 
 * There is an example plugin with full source in plugins/ikpMP3, which
 * adds MP3 audio decoding capabilities to irrKlang.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section staticLib Using irrKlang as static Lib
 *
 * 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.
 *
 * To use irrKlang in this way, just define IRRKLANG_STATIC before including irrklang.h, like this:
 *
 * \code
 * #define IRRKLANG_STATIC
 * #include <irrKlang.h>
 * \endcode
 *
 * Of course, IRRKLANG_STATIC can also simply be defined in the project/compiler settings instead of
 * in the source file.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section enumeratingDevices Enumerating sound devices
 *
 * 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 irrklang::createSoundDeviceList() 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: 
 *
 * \code
 * int main(int argc, const char** argv)
 * {
 *	// enumerate devices
 * 
 * 	irrklang::ISoundDeviceList* deviceList = createSoundDeviceList();
 * 
 * 	// ask user for a sound device
 * 
 * 	printf("Devices available:\n\n");
 * 
 * 	for (int i=0; i<deviceList->getDeviceCount(); ++i)
 * 		printf("%d: %s\n", i, deviceList->getDeviceDescription(i));
 * 
 * 	printf("\nselect a device using the number (or press any key to use default):\n\n");
 * 	int deviceNumber = getch() - '0';
 * 
 * 	// create device with the selected driver
 * 
 * 	const char* deviceID = deviceList->getDeviceID(deviceNumber);
 * 		
 * 	ISoundEngine* engine = createIrrKlangDevice(irrklang::ESOD_AUTO_DETECT, 
 * 	                                            irrklang::ESEO_DEFAULT_OPTIONS,
 * 	                                            deviceID);
 * 
 * 	deviceList->drop(); // delete device list
 *
 *  // ... use engine now
 * } 
 * \endcode
 *
 * 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: createSoundDeviceList() 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 createIrrKlangDevice(), if it is 
 * other than irrklang::ESOD_AUTO_DETECT.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section recordingAudio Recording Audio
 *
 * irrKlang is able to record audio from sound capturing devices such as microphones (currently only 
 * supported in windows). Use the irrklang::IAudioRecorder interface to do this. The following example shows how
 * to record some audio and play it back again using the engine: 
 *
 * \code
 * int main(int argc, const char** argv)
 * {
 *	irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice();
 *	irrklang::IAudioRecorder* recorder = irrklang::createIrrKlangAudioRecorder(engine);
 *
 *	if (!engine || !recorder)
 *	{
 *		printf("Could not create audio engine or audio recoder\n");
 *		return 1;
 *	}
 *
 *	printf("\nPress any key to start recording audio...\n");
 *	getch();
 *
 *	// record some audio
 *
 *	recorder->startRecordingBufferedAudio();
 *
 *	printf("\nRECORDING. Press any key to stop...\n");
 *	getch();
 *
 *	recorder->stopRecordingAudio();
 *
 *	printf("\nRecording done, recorded %dms of audio.\n", 
 *		recorder->getAudioFormat().FrameCount * 1000 / recorder->getAudioFormat().SampleRate );
 *	printf("Press any key to play back recorded audio...\n");
 *	getch();
 *
 *	// play the recorded audio
 *	recorder->addSoundSourceFromRecordedAudio("myRecordedVoice");
 *	engine->play2D("myRecordedVoice", true);
 *
 *	// wait until user presses a key
 *	printf("\nPress any key to quit...");
 *	getch();
 *
 *	recorder->drop();
 *	engine->drop(); // delete engine
 *
 *	return 0;
 * } 
 * \endcode
 *
 * 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:
 *
 * \code
 *  // enumerate recording devices and ask user to select one
 * 
 *  irrklang::ISoundDeviceList* deviceList = irrklang::createAudioRecorderDeviceList();
 *
 *  printf("Devices available:\n\n");
 *
 *  for (int i=0; i<deviceList->getDeviceCount(); ++i)
 *           printf("%d: %s\n", i, deviceList->getDeviceDescription(i));
 *
 *  printf("\nselect a device using the number (or press any key to use default):\n\n");
 *  int deviceNumber = getch() - '0';
 *
 *  // create recording device with the selected driver
 *
 *  const char* deviceID = deviceList->getDeviceID(deviceNumber);
 *  irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice();
 *  irrklang::IAudioRecorder* recorder = 
 *     irrklang::createIrrKlangAudioRecorder(engine, irrklang::ESOD_AUTO_DETECT, deviceID);
 *
 * \endcode
 *
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 * \section unicode Unicode support
 *
 * 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 makeUTF8fromUTF16string() to 
 * convert your wchar_t* string to a char* string.
 *
 * This example shows how:
 *
 * \code
 * const wchar_t* yourFilename = L"SomeUnicodeFilename.wav"; // assuming this is the file name you get from some of your functions
 *
 * const int nBufferSize = 2048; // large enough, but best would be wcslen(yourFilename)*3.
 * char strBuffer[nBufferSize]; 
 * irrklang::makeUTF8fromUTF16string(yourFilename, strBuffer, nBufferSize);
 *
 * // now the converted file name is in strBuffer. We can play it for example now:
 * engine->play2D(strBuffer);
 * \endcode
 *
 * Of course, you can use any other unicode converion function for this. makeUTF8fromUTF16string() is only provided
 * for convenience.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 *
 *
 * \section quickstartexample Quick Start Example
 *
 * To simply start the engine and play a mp3 file, use code like this:
 *
 * \code
 * #include <iostream>
 * #include <irrKlang.h>
 * #pragma comment(lib, "irrKlang.lib") // link with irrKlang.dll
 *
 * int main(int argc, const char** argv)
 * {
 *	irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice();
 *	if (!engine) return 1; // could not start engine
 *
 *	engine->play2D("someMusic.mp3", true); // play some mp3 file, looped
 * 
 *	std::cin.get(); // wait until user presses a key
 * 
 *	engine->drop(); // delete engine
 *	return 0;
 * } 
 * \endcode
 *
 * 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 irrklang. If you don't want to write 
 * this in front of every class and function you are using, simply write 
 *
 * \code
 * using namespace irrklang;
 * \endcode
 * in front of your code, as also shown in the next example.
 * <br/>
 * <br/>
 * <br/>
 * <br/>
 *
 *
 *
 * \section quickstartexample2 Quick Start Example 2
 *
 * 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.
 *
 * \code
 * #include <iostream>
 * #include <irrKlang.h>
 * using namespace irrklang;
 *
 * #pragma comment(lib, "irrKlang.lib") // link with irrKlang.dll
 *
 *
 * int main(int argc, const char** argv)
 * {
 * 	// start the sound engine with default parameters
 * 	ISoundEngine* engine = createIrrKlangDevice();
 *
 * 	if (!engine)
 * 		return 0; // error starting up the engine
 *
 * 	// play some sound stream, looped
 * 	engine->play2D("../../media/helltroopers.ogg", true);
 *
 * 	std::cout << "\nHello World!\n";
 *
 * 	char i = 0;
 *
 * 	while(i != 'q')
 * 	{
 * 		std::cout << "Press any key to play some sound, press 'q' to quit.\n";
 *
 * 		// play a single sound
 * 		engine->play2D("../../media/bell.wav");
 *
 * 		std::cin >> i; // wait for user to press some key
 * 	}
 *
 * 	engine->drop(); // delete engine
 * 	return 0;
 * }
 *
 * \endcode
 */

#if defined(IRRKLANG_STATIC)
    #define IRRKLANG_API
#else
    #if (defined(WIN32) || defined(WIN64) || defined(_MSC_VER))
        #ifdef IRRKLANG_EXPORTS
        #define IRRKLANG_API __declspec(dllexport)
        #else
        #define IRRKLANG_API __declspec(dllimport)
        #endif // IRRKLANG_EXPORT
    #else
        #define IRRKLANG_API __attribute__((visibility("default")))
    #endif // defined(WIN32) || defined(WIN64)
#endif // IRRKLANG_STATIC

#if defined(_STDCALL_SUPPORTED)
#define IRRKLANGCALLCONV __stdcall  // Declare the calling convention.
#else
#define IRRKLANGCALLCONV
#endif // STDCALL_SUPPORTED

//! Everything in the irrKlang Sound Engine can be found in this namespace.
namespace irrklang
{
	//! Creates an irrKlang device. The irrKlang device is the root object for using the sound engine.
	/** \param driver The sound output driver to be used for sound output. Use irrklang::ESOD_AUTO_DETECT
	to let irrKlang decide which driver will be best.
	\param options A combination of irrklang::E_SOUND_ENGINE_OPTIONS literals. Default value is 
	irrklang::ESEO_DEFAULT_OPTIONS.
	\param deviceID Some additional optional deviceID for the audio driver. If not needed, simple
	set this to 0. 
	This can be used for example to set a specific ALSA output pcm device for output
	("default" or "hw", for example). For most driver types, available deviceIDs can be 
	enumerated using createSoundDeviceList().
	See @ref enumeratingDevices for an example or ISoundDeviceList or details.
	\param sdk_version_do_not_use Don't use or change this parameter. Always set it to
	IRRKLANG_SDK_VERSION, which is done by default. This is needed for sdk version checks.
	\return Returns pointer to the created irrKlang device or null if the
	device could not be created. If you don't need the device, use ISoundEngine::drop() to
	delete it. See IRefCounted::drop() for details.
	*/
	IRRKLANG_API ISoundEngine* IRRKLANGCALLCONV createIrrKlangDevice(
		E_SOUND_OUTPUT_DRIVER driver = ESOD_AUTO_DETECT,
		int options = ESEO_DEFAULT_OPTIONS,
		const char* deviceID = 0,
		const char* sdk_version_do_not_use = IRR_KLANG_VERSION);


	//! Creates a list of available sound devices for the driver type. 
	/** The device IDs in this list can be used as parameter to createIrrKlangDevice() to
	make irrKlang use a special sound device. See @ref enumeratingDevices for an example on how
	to use this.
	\param driver The sound output driver of which the list is generated. Set it irrklang::ESOD_AUTO_DETECT
	to let this function use the same device as createIrrKlangDevice() would choose.
	\param sdk_version_do_not_use Don't use or change this parameter. Always set it to
	IRRKLANG_SDK_VERSION, which is done by default. This is needed for sdk version checks.
	\return Returns a pointer to the list of enumerated sound devices for the selected sound driver.
	The device IDs in this list can be used as parameter to createIrrKlangDevice() to
	make irrKlang use a special sound device. 
	After you don't need the list anymore, call ISoundDeviceList::drop() in order to free its memory. */
	IRRKLANG_API ISoundDeviceList* IRRKLANGCALLCONV createSoundDeviceList(
		E_SOUND_OUTPUT_DRIVER driver = ESOD_AUTO_DETECT,
		const char* sdk_version_do_not_use = IRR_KLANG_VERSION);


	//! Creates an irrKlang audio recording device. The IAudioRecorder is the root object for recording audio.
	/** If you want to play back recorded audio as well, create the ISoundEngine first using
	createIrrKlangDevice() and then the IAudioRecorder using createIrrKlangAudioRecorder(), where
	you set the ISoundEngine as first parameter. See @ref recordingAudio for an example on how to use this.
	Note: audio recording is a very new feature a still beta in irrKlang. It currently only works in Windows
	and with DirectSound (subject to change).
	\param irrKlangDeviceForPlayback A pointer to the already existing sound device used for playback
	of audio. Sound sources recorded with the IAudioRecorder will be added into that device so that
	they can be played back there.
	\param driver The sound output driver to be used for recording audio. Use irrklang::ESOD_AUTO_DETECT
	to let irrKlang decide which driver will be best.
	\param deviceID Some additional optional deviceID for the audio driver. If not needed, simple
	set this to 0. Use createAudioRecorderDeviceList() to get a list of all deviceIDs.
	\param sdk_version_do_not_use Don't use or change this parameter. Always set it to
	IRRKLANG_SDK_VERSION, which is done by default. This is needed for sdk version checks.
	\return Returns pointer to the created irrKlang device or null if the
	device could not be created. If you don't need the device, use ISoundEngine::drop() to
	delete it. See IRefCounted::drop() for details.
	*/
	IRRKLANG_API IAudioRecorder* IRRKLANGCALLCONV createIrrKlangAudioRecorder(
		ISoundEngine* irrKlangDeviceForPlayback,
		E_SOUND_OUTPUT_DRIVER driver = ESOD_AUTO_DETECT,
		const char* deviceID = 0,
		const char* sdk_version_do_not_use = IRR_KLANG_VERSION);

	//! Creates a list of available recording devices for the driver type. 
	/** The device IDs in this list can be used as parameter to createIrrKlangAudioRecorder() to
	make irrKlang use a special recording device. 
	\param driver The sound output driver of which the list is generated. Set it irrklang::ESOD_AUTO_DETECT
	to let this function use the same device as createIrrKlangDevice() would choose.
	\param sdk_version_do_not_use Don't use or change this parameter. Always set it to
	IRRKLANG_SDK_VERSION, which is done by default. This is needed for sdk version checks.
	\return Returns a pointer to the list of enumerated recording devices for the selected sound driver.
	The device IDs in this list can be used as parameter to createIrrKlangAudioRecorder() to
	make irrKlang use a special sound device. 
	After you don't need the list anymore, call ISoundDeviceList::drop() in order to free its memory. */
	IRRKLANG_API ISoundDeviceList* IRRKLANGCALLCONV createAudioRecorderDeviceList(
		E_SOUND_OUTPUT_DRIVER driver = ESOD_AUTO_DETECT,
		const char* sdk_version_do_not_use = IRR_KLANG_VERSION);


	//! Converts a wchar_t string to an utf8 string, useful when using Windows in unicode mode. 
	/** irrKlang works with unicode file names, and accepts char* strings as parameters for names and filenames.
	If you are running irrKlang in Windows, and working with wchar_t* pointers instead of char* ones, 
	you can use this function to create a char* (UTF8) representation of your wchar_t* (UTF16) string.
	Works for filenames and other strings.
	\param pInputString zero terminated input string.
	\param pOutputBuffer the buffer where the converted string is written to. Be sure that this buffer
	has a big enough size. A good size would be three times the string length of your input buffer, like
	wcslen(yourInputBuffer)*3. Because each wchar_t can be represented by up to 3 chars.
	\param outputBufferSize size of your output buffer.
	\return Returns true if successful, and false if not. If 'false' is returned, maybe your buffer was too small. */
	IRRKLANG_API bool IRRKLANGCALLCONV makeUTF8fromUTF16string(
		const wchar_t* pInputString, char* pOutputBuffer, int outputBufferSize);


} // end namespace irrklang


/*! \file irrKlang.h
    \brief Main header file of the irrKlang sound library, the only file needed to include.
*/

#endif