- * @ref intro
- * @ref features
- * @ref links
- * @ref tipsandtricks
- *
- * Programming irrKlang:
- * @ref concept
- * @ref playingSounds
- * @ref changingSounds
- * @ref soundSources
- * @ref sound3d
- * @ref removingSounds
- * @ref events
- * @ref memoryPlayback
- * @ref effects
- * @ref fileOverriding
- * @ref audioDecoders
- * @ref plugins
- * @ref staticLib
- * @ref enumeratingDevices
- * @ref recordingAudio
- * @ref unicode
- *
- * Short full examples:
- * @ref quickstartexample
- * @ref quickstartexample2
- *
- *
- * - * \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 - * http://www.ambiera.com/irrklang - * 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. - * - *
- *
- * - * - * \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 - *
-
- *
- RIFF WAVE (*.wav) - *
- Ogg Vorbis (*.ogg) - *
- MPEG-1 Audio Layer 3 (*.mp3) - *
- Free Lossless Audio Codec (*.flac) - *
- Amiga Modules (*.mod) - *
- Impulse Tracker (*.it) - *
- Scream Tracker 3 (*.s3d) - *
- Fast Tracker 2 (*.xm) - *
-
- *
- Windows 98, ME, NT 4, 2000, XP, Vista, Windows 7, Windows 8 - *
- DirectSound - *
- DirectSound8 - *
- WinMM - *
- Linux / *nix - *
- ALSA - *
- MacOSX (x86 and PPC) - *
- CoreAudio - *
-
- *
-
- *
-
- *
- *
- *
- * - * - * - * \section links Links into the API documentation - * - * irrklang::ISoundEngine: The main class of irrKlang.
- * Class list: List of all classes with descriptions.
- * Class members: Good place to find forgotten features.
- *
- *
- *
- * - * - * - * \section tipsandtricks Tips and Tricks - * - * This section lists a few tips you might consider when implementing the sound part of your application - * using irrKlang: - * - *
-
- *
- 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. - *
- 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. - *
- 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.) - *
- *
- *
- *
- * - * - * - * \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.
- * To start up the sound engine, you simply need to call createIrrKlangDevice(). To shut it down, - * call IRefCounted::drop(): - * - * \code - * #include
- *
- *
- *
- * - * - * - * \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.
- * 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. - *
- *
- *
- *
- * - * - * \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. - *
- *
- *
- *
- * - * - * \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. - *
- *
- *
- *
- * - * - * - * \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 - * - *
- *
- *
- *
- * - * - * \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. - *
- *
- *
- *
- * - * - * - * \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.
- * 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.
- * 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. - *
- *
- *
- *
- * - * - * - * \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. - *
- *
- *
- *
- * - * - * - * \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.
- * - * 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. - *
- *
- *
- *
- * - * - * - * \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.
- * - * 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. - *
- *
- *
- *
- * - * - * - * \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. - *
- *
- *
- *
- * - * - * - * \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.
- * - * 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.
- * - * There is an example plugin with full source in plugins/ikpMP3, which - * adds MP3 audio decoding capabilities to irrKlang. - *
- *
- *
- *
- * - * - * - * \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
- *
- *
- *
- * - * - * - * \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
- * 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. - *
- *
- *
- *
- * - * - * - * \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
- *
- *
- *
- * - * - * \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. - *
- *
- *
- *
- * - * - * - * - * - * \section quickstartexample Quick Start Example - * - * To simply start the engine and play a mp3 file, use code like this: - * - * \code - * #include
- *
- *
- *
- * - * - * - * \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
mhA6(GP?ER);?il&JQ4@tX&MUwz
zVyiXX58;^P@Z)ML_eYxkGVdVa9t~ybeA3ljegh#=)jqMi%b!%Yeu)dctO@@c1dID!
ztdEFG(cLcZA3A+oi;hSg?yuNL5SRD2A0#7R>6k*%hBwl^T~kIF>A2qTM&#cG&8w89
zmwyJU@$5gQ)A7&jeE&;OU&U6jUmT7cROa|qabI`i&ETW0FTKkr4yW9jm