diff --git a/src/dep/include/irrklang/ik_ESoundEngineOptions.h b/src/dep/include/irrklang/ik_ESoundEngineOptions.h index 8cf37d6..ca31134 100644 --- a/src/dep/include/irrklang/ik_ESoundEngineOptions.h +++ b/src/dep/include/irrklang/ik_ESoundEngineOptions.h @@ -1,78 +1,78 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __E_IRRKLANG_SOUND_ENGINE_OPTIONS_H_INCLUDED__ -#define __E_IRRKLANG_SOUND_ENGINE_OPTIONS_H_INCLUDED__ - -namespace irrklang -{ - //! An enumeration for all options for starting up the sound engine - /** When using createIrrKlangDevice, use a combination of this these - as 'options' parameter to start up the engine. By default, irrKlang - uses ESEO_DEFAULT_OPTIONS, which is set to the combination - ESEO_MULTI_THREADED | ESEO_LOAD_PLUGINS | ESEO_USE_3D_BUFFERS | ESEO_PRINT_DEBUG_INFO_TO_DEBUGGER | ESEO_PRINT_DEBUG_INFO_TO_STDOUT. */ - enum E_SOUND_ENGINE_OPTIONS - { - //! If specified (default), it will make irrKlang run in a separate thread. - /** Using this flag, irrKlang will update - all streams, sounds, 3d positions and whatever automaticly. You also don't need to call ISoundEngine::update() - if irrKlang is running multithreaded. However, if you want to run irrKlang in the same thread - as your application (for easier debugging for example), don't set this. But you need to call ISoundEngine::update() - as often as you can (at least about 2-3 times per second) to make irrKlang update everything correctly then. */ - ESEO_MULTI_THREADED = 0x01, - - //! If the window of the application doesn't have the focus, irrKlang will be silent if this has been set. - /** This will only work when irrKlang is using the DirectSound output driver. */ - ESEO_MUTE_IF_NOT_FOCUSED = 0x02, - - //! Automaticly loads external plugins when starting up. - /** Plugins usually are .dll, .so or .dylib - files named for example ikpMP3.dll (= short for irrKlangPluginMP3) which are executed - after the startup of the sound engine and modify it for example to make it possible - to play back mp3 files. Plugins are being loaded from the current working directory - as well as from the position where the .exe using the irrKlang library resides. - It is also possible to load the plugins after the engine has started up using - ISoundEngine::loadPlugins(). */ - ESEO_LOAD_PLUGINS = 0x04, - - //! Uses 3D sound buffers instead of emulating them when playing 3d sounds (default). - /** If this flag is not specified, all buffers will by created - in 2D only and 3D positioning will be emulated in software, making the engine run - faster if hardware 3d audio is slow on the system. */ - ESEO_USE_3D_BUFFERS = 0x08, - - //! Prints debug messages to the debugger window. - /** irrKlang will print debug info and status messages to any windows debugger supporting - OutputDebugString() (like VisualStudio). - This is useful if your application does not capture any console output (see ESEO_PRINT_DEBUG_INFO_TO_STDOUT). */ - ESEO_PRINT_DEBUG_INFO_TO_DEBUGGER = 0x10, - - //! Prints debug messages to stdout (the ConsoleWindow). - /** irrKlang will print debug info and status messages stdout, the console window in Windows. */ - ESEO_PRINT_DEBUG_INFO_TO_STDOUT = 0x20, - - //! Uses linear rolloff for 3D sound. - /** If specified, instead of the default logarithmic one, irrKlang will - use a linear rolloff model which influences the attenuation - of the sounds over distance. The volume is interpolated linearly between the MinDistance - and MaxDistance, making it possible to adjust sounds more easily although this is not - physically correct. - Note that this option may not work when used together with the ESEO_USE_3D_BUFFERS - option when using Direct3D for example, irrKlang will then turn off ESEO_USE_3D_BUFFERS - automaticly to be able to use this option and write out a warning. */ - ESEO_LINEAR_ROLLOFF = 0x40, - - //! Default parameters when starting up the engine. - ESEO_DEFAULT_OPTIONS = ESEO_MULTI_THREADED | ESEO_LOAD_PLUGINS | ESEO_USE_3D_BUFFERS | ESEO_PRINT_DEBUG_INFO_TO_DEBUGGER | ESEO_PRINT_DEBUG_INFO_TO_STDOUT, - - //! Never used, it only forces the compiler to compile these enumeration values to 32 bit. - /** Don't use this. */ - ESEO_FORCE_32_BIT = 0x7fffffff - }; - -} // end namespace irrklang - - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __E_IRRKLANG_SOUND_ENGINE_OPTIONS_H_INCLUDED__ +#define __E_IRRKLANG_SOUND_ENGINE_OPTIONS_H_INCLUDED__ + +namespace irrklang +{ + //! An enumeration for all options for starting up the sound engine + /** When using createIrrKlangDevice, use a combination of this these + as 'options' parameter to start up the engine. By default, irrKlang + uses ESEO_DEFAULT_OPTIONS, which is set to the combination + ESEO_MULTI_THREADED | ESEO_LOAD_PLUGINS | ESEO_USE_3D_BUFFERS | ESEO_PRINT_DEBUG_INFO_TO_DEBUGGER | ESEO_PRINT_DEBUG_INFO_TO_STDOUT. */ + enum E_SOUND_ENGINE_OPTIONS + { + //! If specified (default), it will make irrKlang run in a separate thread. + /** Using this flag, irrKlang will update + all streams, sounds, 3d positions and whatever automaticly. You also don't need to call ISoundEngine::update() + if irrKlang is running multithreaded. However, if you want to run irrKlang in the same thread + as your application (for easier debugging for example), don't set this. But you need to call ISoundEngine::update() + as often as you can (at least about 2-3 times per second) to make irrKlang update everything correctly then. */ + ESEO_MULTI_THREADED = 0x01, + + //! If the window of the application doesn't have the focus, irrKlang will be silent if this has been set. + /** This will only work when irrKlang is using the DirectSound output driver. */ + ESEO_MUTE_IF_NOT_FOCUSED = 0x02, + + //! Automaticly loads external plugins when starting up. + /** Plugins usually are .dll, .so or .dylib + files named for example ikpMP3.dll (= short for irrKlangPluginMP3) which are executed + after the startup of the sound engine and modify it for example to make it possible + to play back mp3 files. Plugins are being loaded from the current working directory + as well as from the position where the .exe using the irrKlang library resides. + It is also possible to load the plugins after the engine has started up using + ISoundEngine::loadPlugins(). */ + ESEO_LOAD_PLUGINS = 0x04, + + //! Uses 3D sound buffers instead of emulating them when playing 3d sounds (default). + /** If this flag is not specified, all buffers will by created + in 2D only and 3D positioning will be emulated in software, making the engine run + faster if hardware 3d audio is slow on the system. */ + ESEO_USE_3D_BUFFERS = 0x08, + + //! Prints debug messages to the debugger window. + /** irrKlang will print debug info and status messages to any windows debugger supporting + OutputDebugString() (like VisualStudio). + This is useful if your application does not capture any console output (see ESEO_PRINT_DEBUG_INFO_TO_STDOUT). */ + ESEO_PRINT_DEBUG_INFO_TO_DEBUGGER = 0x10, + + //! Prints debug messages to stdout (the ConsoleWindow). + /** irrKlang will print debug info and status messages stdout, the console window in Windows. */ + ESEO_PRINT_DEBUG_INFO_TO_STDOUT = 0x20, + + //! Uses linear rolloff for 3D sound. + /** If specified, instead of the default logarithmic one, irrKlang will + use a linear rolloff model which influences the attenuation + of the sounds over distance. The volume is interpolated linearly between the MinDistance + and MaxDistance, making it possible to adjust sounds more easily although this is not + physically correct. + Note that this option may not work when used together with the ESEO_USE_3D_BUFFERS + option when using Direct3D for example, irrKlang will then turn off ESEO_USE_3D_BUFFERS + automaticly to be able to use this option and write out a warning. */ + ESEO_LINEAR_ROLLOFF = 0x40, + + //! Default parameters when starting up the engine. + ESEO_DEFAULT_OPTIONS = ESEO_MULTI_THREADED | ESEO_LOAD_PLUGINS | ESEO_USE_3D_BUFFERS | ESEO_PRINT_DEBUG_INFO_TO_DEBUGGER | ESEO_PRINT_DEBUG_INFO_TO_STDOUT, + + //! Never used, it only forces the compiler to compile these enumeration values to 32 bit. + /** Don't use this. */ + ESEO_FORCE_32_BIT = 0x7fffffff + }; + +} // end namespace irrklang + + +#endif + diff --git a/src/dep/include/irrklang/ik_ESoundOutputDrivers.h b/src/dep/include/irrklang/ik_ESoundOutputDrivers.h index 537e8c6..b08ecb8 100644 --- a/src/dep/include/irrklang/ik_ESoundOutputDrivers.h +++ b/src/dep/include/irrklang/ik_ESoundOutputDrivers.h @@ -1,56 +1,59 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __E_IRRKLANG_SOUND_OUTPUT_DRIVERS_H_INCLUDED__ -#define __E_IRRKLANG_SOUND_OUTPUT_DRIVERS_H_INCLUDED__ - -namespace irrklang -{ - //! An enumeration for all types of supported sound drivers - /** Values of this enumeration can be used as parameter when calling createIrrKlangDevice(). */ - enum E_SOUND_OUTPUT_DRIVER - { - //! Autodetects the best sound driver for the system - ESOD_AUTO_DETECT = 0, - - //! DirectSound8 sound output driver, windows only. - /** In contrast to ESOD_DIRECT_SOUND, this supports sophisticated sound effects - but may not be available on old windows versions. It behaves very similar - to ESOD_DIRECT_SOUND but also supports DX8 sound effects.*/ - ESOD_DIRECT_SOUND_8, - - //! DirectSound sound output driver, windows only. - /* This uses DirectSound 3 or above, if available. If DX8 sound effects - are needed, use ESOD_DIRECT_SOUND_8 instead. The - ESOD_DIRECT_SOUND driver may be available on more and older windows - versions than ESOD_DIRECT_SOUND_8.*/ - ESOD_DIRECT_SOUND, - - //! WinMM sound output driver, windows only. - ESOD_WIN_MM, - - //! ALSA sound output driver, linux only. - /* When using ESOD_ALSA in createIrrKlangDevice(), it is possible to set the third parameter, - 'deviceID' to the name of specific ALSA pcm device, to the irrKlang force to use this one. - Set it to 'default', or 'plug:hw' or whatever you need it to be.*/ - ESOD_ALSA, - - //! Core Audio sound output driver, mac os only. - ESOD_CORE_AUDIO, - - //! Null driver, creating no sound output - ESOD_NULL, - - //! Amount of built-in sound output drivers - ESOD_COUNT, - - //! This enumeration literal is never used, it only forces the compiler to - //! compile these enumeration values to 32 bit. - ESOD_FORCE_32_BIT = 0x7fffffff - }; - -} // end namespace irrklang - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __E_IRRKLANG_SOUND_OUTPUT_DRIVERS_H_INCLUDED__ +#define __E_IRRKLANG_SOUND_OUTPUT_DRIVERS_H_INCLUDED__ + +namespace irrklang +{ + //! An enumeration for all types of supported sound drivers + /** Values of this enumeration can be used as parameter when calling createIrrKlangDevice(). */ + enum E_SOUND_OUTPUT_DRIVER + { + //! Autodetects the best sound driver for the system + ESOD_AUTO_DETECT = 0, + + //! DirectSound8 sound output driver, windows only. + /** In contrast to ESOD_DIRECT_SOUND, this supports sophisticated sound effects + but may not be available on old windows versions. It behaves very similar + to ESOD_DIRECT_SOUND but also supports DX8 sound effects.*/ + ESOD_DIRECT_SOUND_8, + + //! DirectSound sound output driver, windows only. + /** This uses DirectSound 3 or above, if available. If DX8 sound effects + are needed, use ESOD_DIRECT_SOUND_8 instead. The + ESOD_DIRECT_SOUND driver may be available on more and older windows + versions than ESOD_DIRECT_SOUND_8.*/ + ESOD_DIRECT_SOUND, + + //! WinMM sound output driver, windows only. + /** Supports the ISoundMixedOutputReceiver interface using setMixedDataOutputReceiver. */ + ESOD_WIN_MM, + + //! ALSA sound output driver, linux only. + /** When using ESOD_ALSA in createIrrKlangDevice(), it is possible to set the third parameter, + 'deviceID' to the name of specific ALSA pcm device, to the irrKlang force to use this one. + Set it to 'default', or 'plug:hw' or whatever you need it to be. + Supports the ISoundMixedOutputReceiver interface using setMixedDataOutputReceiver. */ + ESOD_ALSA, + + //! Core Audio sound output driver, mac os only. + /** Supports the ISoundMixedOutputReceiver interface using setMixedDataOutputReceiver. */ + ESOD_CORE_AUDIO, + + //! Null driver, creating no sound output + ESOD_NULL, + + //! Amount of built-in sound output drivers + ESOD_COUNT, + + //! This enumeration literal is never used, it only forces the compiler to + //! compile these enumeration values to 32 bit. + ESOD_FORCE_32_BIT = 0x7fffffff + }; + +} // end namespace irrklang + +#endif + diff --git a/src/dep/include/irrklang/ik_EStreamModes.h b/src/dep/include/irrklang/ik_EStreamModes.h index e124022..fef1869 100644 --- a/src/dep/include/irrklang/ik_EStreamModes.h +++ b/src/dep/include/irrklang/ik_EStreamModes.h @@ -1,31 +1,31 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __E_IRRKLANG_STREAM_MODES_H_INCLUDED__ -#define __E_IRRKLANG_STREAM_MODES_H_INCLUDED__ - -namespace irrklang -{ - //! An enumeration for all types of supported stream modes - enum E_STREAM_MODE - { - //! Autodetects the best stream mode for a specified audio data. - ESM_AUTO_DETECT = 0, - - //! Streams the audio data when needed. - ESM_STREAMING, - - //! Loads the whole audio data into the memory. - ESM_NO_STREAMING, - - //! This enumeration literal is never used, it only forces the compiler to - //! compile these enumeration values to 32 bit. - ESM_FORCE_32_BIT = 0x7fffffff - }; - -} // end namespace irrklang - - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __E_IRRKLANG_STREAM_MODES_H_INCLUDED__ +#define __E_IRRKLANG_STREAM_MODES_H_INCLUDED__ + +namespace irrklang +{ + //! An enumeration for all types of supported stream modes + enum E_STREAM_MODE + { + //! Autodetects the best stream mode for a specified audio data. + ESM_AUTO_DETECT = 0, + + //! Streams the audio data when needed. + ESM_STREAMING, + + //! Loads the whole audio data into the memory. + ESM_NO_STREAMING, + + //! This enumeration literal is never used, it only forces the compiler to + //! compile these enumeration values to 32 bit. + ESM_FORCE_32_BIT = 0x7fffffff + }; + +} // end namespace irrklang + + +#endif + diff --git a/src/dep/include/irrklang/ik_IAudioRecorder.h b/src/dep/include/irrklang/ik_IAudioRecorder.h index 1a42bb2..c8cdb78 100644 --- a/src/dep/include/irrklang/ik_IAudioRecorder.h +++ b/src/dep/include/irrklang/ik_IAudioRecorder.h @@ -1,104 +1,110 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_AUDIO_RECORDER_H_INCLUDED__ -#define __I_IRRKLANG_AUDIO_RECORDER_H_INCLUDED__ - -#include "ik_IRefCounted.h" -#include "ik_ISoundSource.h" - - -namespace irrklang -{ - class ICapturedAudioDataReceiver; - - //! Interface to an audio recorder. Create it using the createIrrKlangAudioRecorder() function. - /** It creates sound sources into an ISoundEngine which then can be played there. - See @ref recordingAudio for an example on how to use this. */ - class IAudioRecorder : public virtual IRefCounted - { - public: - - //! Starts recording audio. - /** Clears all possibly previously recorded buffered audio data and starts to record. - When finished recording audio data, call stopRecordingAudio(). - All recorded audio data gets stored into an internal audio buffer, which - can then be accessed for example using addSoundSourceFromRecordedAudio() or - getRecordedAudioData(). For recording audio data not into an internal audio - buffer, use startRecordingCustomHandledAudio(). - \param sampleRate: Sample rate of the recorded audio. - \param sampleFormat: Sample format of the recorded audio. - \return Returns true if successfully started recording and false if not.*/ - virtual bool startRecordingBufferedAudio(ik_s32 sampleRate=22000, ESampleFormat sampleFormat=ESF_S16) = 0; - - //! Starts recording audio. - /** Clears all possibly previously recorded buffered audio data and starts to record - audio data, which is delivered to a custom user callback interface. - When finished recording audio data, call stopRecordingAudio(). If instead of - recording the data to the receiver interface recording into a managed buffer - is wished, use startRecordingBufferedAudio() instead. - \param receiver: Interface to be implemented by the user, gets called once for each - captured audio data chunk. - \param sampleRate: Sample rate of the recorded audio. - \param sampleFormat: Sample format of the recorded audio. - \return Returns true if successfully started recording and false if not. */ - virtual bool startRecordingCustomHandledAudio(ICapturedAudioDataReceiver* receiver, - ik_s32 sampleRate=22000, ESampleFormat sampleFormat=ESF_S16) = 0; - - //! Stops recording audio. - virtual void stopRecordingAudio() = 0; - - //! Creates a sound source for the recorded audio data. - /** The returned sound source pointer then can be used to play back the recorded audio data - using ISoundEngine::play2D(). This method only will succeed if the audio was recorded using - startRecordingBufferedAudio() and audio recording is currently stopped. - \param soundName Name of the virtual sound file (e.g. "someRecordedAudio"). You can also use this - name when calling play3D() or play2D(). */ - virtual ISoundSource* addSoundSourceFromRecordedAudio(const char* soundName) = 0; - - //! Clears recorded audio data buffer, freeing memory. - /** This method will only succeed if audio recording is currently stopped. */ - virtual void clearRecordedAudioDataBuffer() = 0; - - //! Returns if the recorder is currently recording audio. - virtual bool isRecording() = 0; - - //! Returns the audio format of the recorded audio data. - /** Also contains informations about the length of the recorded audio stream. */ - virtual SAudioStreamFormat getAudioFormat() = 0; - - //! Returns a pointer to the recorded audio data. - /** This method will only succeed if audio recording is currently stopped and - something was recorded previously using startRecordingBufferedAudio(). - The lenght of the buffer can be retrieved using - getAudioFormat().getSampleDataSize(). Note that the pointer is only valid - as long as not clearRecordedAudioDataBuffer() is called or another sample is - recorded.*/ - virtual void* getRecordedAudioData() = 0; - - //! returns the name of the sound driver, like 'ALSA' for the alsa device. - /** Possible returned strings are "NULL", "ALSA", "CoreAudio", "winMM", - "DirectSound" and "DirectSound8". */ - virtual const char* getDriverName() = 0; - }; - - - //! Interface to be implemented by the user if access to the recorded audio data is needed. - /** Is used as parameter in IAudioRecorder::startRecordingCustomHandledAudio. */ - class ICapturedAudioDataReceiver : public IRefCounted - { - public: - - //! Gets called once for each captured audio data chunk. - /** See IAudioRecorder::startRecordingCustomHandledAudio for details. - \param audioData: Pointer to a part of the recorded audio data - \param lengthInBytes: Amount of bytes in the audioData buffer.*/ - virtual void OnReceiveAudioDataStreamChunk(unsigned char* audioData, unsigned long lengthInBytes) = 0; - }; - - -} // end namespace irrklang - - -#endif +// Copyright (C) 2002-2008 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_AUDIO_RECORDER_H_INCLUDED__ +#define __I_IRRKLANG_AUDIO_RECORDER_H_INCLUDED__ + +#include "ik_IRefCounted.h" +#include "ik_ISoundSource.h" + + +namespace irrklang +{ + class ICapturedAudioDataReceiver; + + //! Interface to an audio recorder. Create it using the createIrrKlangAudioRecorder() function. + /** It creates sound sources into an ISoundEngine which then can be played there. + See @ref recordingAudio for an example on how to use this. */ + class IAudioRecorder : public virtual IRefCounted + { + public: + + //! Starts recording audio. + /** Clears all possibly previously recorded buffered audio data and starts to record. + When finished recording audio data, call stopRecordingAudio(). + All recorded audio data gets stored into an internal audio buffer, which + can then be accessed for example using addSoundSourceFromRecordedAudio() or + getRecordedAudioData(). For recording audio data not into an internal audio + buffer, use startRecordingCustomHandledAudio(). + \param sampleRate: Sample rate of the recorded audio. + \param sampleFormat: Sample format of the recorded audio. + \param channelCount: Amount of audio channels. + \return Returns true if successfully started recording and false if not.*/ + virtual bool startRecordingBufferedAudio(ik_s32 sampleRate=22000, + ESampleFormat sampleFormat=ESF_S16, + ik_s32 channelCount=1) = 0; + + //! Starts recording audio. + /** Clears all possibly previously recorded buffered audio data and starts to record + audio data, which is delivered to a custom user callback interface. + When finished recording audio data, call stopRecordingAudio(). If instead of + recording the data to the receiver interface recording into a managed buffer + is wished, use startRecordingBufferedAudio() instead. + \param receiver: Interface to be implemented by the user, gets called once for each + captured audio data chunk. + \param sampleRate: Sample rate of the recorded audio. + \param sampleFormat: Sample format of the recorded audio. + \param channelCount: Amount of audio channels. + \return Returns true if successfully started recording and false if not. */ + virtual bool startRecordingCustomHandledAudio(ICapturedAudioDataReceiver* receiver, + ik_s32 sampleRate=22000, + ESampleFormat sampleFormat=ESF_S16, + ik_s32 channelCount=1) = 0; + + //! Stops recording audio. + virtual void stopRecordingAudio() = 0; + + //! Creates a sound source for the recorded audio data. + /** The returned sound source pointer then can be used to play back the recorded audio data + using ISoundEngine::play2D(). This method only will succeed if the audio was recorded using + startRecordingBufferedAudio() and audio recording is currently stopped. + \param soundName Name of the virtual sound file (e.g. "someRecordedAudio"). You can also use this + name when calling play3D() or play2D(). */ + virtual ISoundSource* addSoundSourceFromRecordedAudio(const char* soundName) = 0; + + //! Clears recorded audio data buffer, freeing memory. + /** This method will only succeed if audio recording is currently stopped. */ + virtual void clearRecordedAudioDataBuffer() = 0; + + //! Returns if the recorder is currently recording audio. + virtual bool isRecording() = 0; + + //! Returns the audio format of the recorded audio data. + /** Also contains informations about the length of the recorded audio stream. */ + virtual SAudioStreamFormat getAudioFormat() = 0; + + //! Returns a pointer to the recorded audio data. + /** This method will only succeed if audio recording is currently stopped and + something was recorded previously using startRecordingBufferedAudio(). + The lenght of the buffer can be retrieved using + getAudioFormat().getSampleDataSize(). Note that the pointer is only valid + as long as not clearRecordedAudioDataBuffer() is called or another sample is + recorded.*/ + virtual void* getRecordedAudioData() = 0; + + //! returns the name of the sound driver, like 'ALSA' for the alsa device. + /** Possible returned strings are "NULL", "ALSA", "CoreAudio", "winMM", + "DirectSound" and "DirectSound8". */ + virtual const char* getDriverName() = 0; + }; + + + //! Interface to be implemented by the user if access to the recorded audio data is needed. + /** Is used as parameter in IAudioRecorder::startRecordingCustomHandledAudio. */ + class ICapturedAudioDataReceiver : public IRefCounted + { + public: + + //! Gets called once for each captured audio data chunk. + /** See IAudioRecorder::startRecordingCustomHandledAudio for details. + \param audioData: Pointer to a part of the recorded audio data + \param lengthInBytes: Amount of bytes in the audioData buffer.*/ + virtual void OnReceiveAudioDataStreamChunk(unsigned char* audioData, unsigned long lengthInBytes) = 0; + }; + + +} // end namespace irrklang + + +#endif diff --git a/src/dep/include/irrklang/ik_IAudioStream.h b/src/dep/include/irrklang/ik_IAudioStream.h index 26f986c..4d11a6b 100644 --- a/src/dep/include/irrklang/ik_IAudioStream.h +++ b/src/dep/include/irrklang/ik_IAudioStream.h @@ -1,49 +1,49 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_AUDIO_STREAM_H_INCLUDED__ -#define __I_IRRKLANG_AUDIO_STREAM_H_INCLUDED__ - -#include "ik_IRefCounted.h" -#include "ik_SAudioStreamFormat.h" - -namespace irrklang -{ - - -//! Reads and decodes audio data into an usable audio stream for the ISoundEngine -class IAudioStream : public IRefCounted -{ -public: - - //! destructor - virtual ~IAudioStream() {}; - - //! returns format of the audio stream - virtual SAudioStreamFormat getFormat() = 0; - - //! sets the position of the audio stream. - /** For example to let the stream be read from the beginning of the file again, - setPosition(0) would be called. This is usually done be the sound engine to - loop a stream after if has reached the end. Return true if sucessful and 0 if not. - \param pos: Position in frames.*/ - virtual bool setPosition(ik_s32 pos) = 0; - - //! returns true if the audio stream is seekable - /* Some file formats like (MODs) don't support seeking */ - virtual bool getIsSeekingSupported() { return true; } - - //! tells the audio stream to read frameCountToRead audio frames into the specified buffer - /** \param target: Target data buffer to the method will write the read frames into. The - specified buffer will be at least getFormat().getFrameSize()*frameCountToRead bytes big. - \param frameCountToRead: amount of frames to be read. - \returns Returns amount of frames really read. Should be frameCountToRead in most cases. */ - virtual ik_s32 readFrames(void* target, ik_s32 frameCountToRead) = 0; -}; - - -} // end namespace irrklang - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_AUDIO_STREAM_H_INCLUDED__ +#define __I_IRRKLANG_AUDIO_STREAM_H_INCLUDED__ + +#include "ik_IRefCounted.h" +#include "ik_SAudioStreamFormat.h" + +namespace irrklang +{ + + +//! Reads and decodes audio data into an usable audio stream for the ISoundEngine +class IAudioStream : public IRefCounted +{ +public: + + //! destructor + virtual ~IAudioStream() {}; + + //! returns format of the audio stream + virtual SAudioStreamFormat getFormat() = 0; + + //! sets the position of the audio stream. + /** For example to let the stream be read from the beginning of the file again, + setPosition(0) would be called. This is usually done be the sound engine to + loop a stream after if has reached the end. Return true if sucessful and 0 if not. + \param pos: Position in frames.*/ + virtual bool setPosition(ik_s32 pos) = 0; + + //! returns true if the audio stream is seekable + /* Some file formats like (MODs) don't support seeking */ + virtual bool getIsSeekingSupported() { return true; } + + //! tells the audio stream to read frameCountToRead audio frames into the specified buffer + /** \param target: Target data buffer to the method will write the read frames into. The + specified buffer will be at least getFormat().getFrameSize()*frameCountToRead bytes big. + \param frameCountToRead: amount of frames to be read. + \returns Returns amount of frames really read. Should be frameCountToRead in most cases. */ + virtual ik_s32 readFrames(void* target, ik_s32 frameCountToRead) = 0; +}; + + +} // end namespace irrklang + +#endif + diff --git a/src/dep/include/irrklang/ik_IAudioStreamLoader.h b/src/dep/include/irrklang/ik_IAudioStreamLoader.h index 39b9fc1..5a2a7f2 100644 --- a/src/dep/include/irrklang/ik_IAudioStreamLoader.h +++ b/src/dep/include/irrklang/ik_IAudioStreamLoader.h @@ -1,40 +1,40 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_AUDIO_STREAM_LOADER_H_INCLUDED__ -#define __I_IRRKLANG_AUDIO_STREAM_LOADER_H_INCLUDED__ - -#include "ik_IRefCounted.h" -#include "ik_IFileReader.h" - -namespace irrklang -{ - -class IAudioStream; - -//! Class which is able to create an audio file stream from a file. -class IAudioStreamLoader : public IRefCounted -{ -public: - - //! destructor - virtual ~IAudioStreamLoader() {}; - - //! Returns true if the file maybe is able to be loaded by this class. - /** This decision should be based only on the file extension (e.g. ".wav"). The given - filename string is guaranteed to be lower case. */ - virtual bool isALoadableFileExtension(const ik_c8* fileName) = 0; - - //! Creates an audio file input stream from a file - /** \return Pointer to the created audio stream. Returns 0 if loading failed. - If you no longer need the stream, you should call IAudioFileStream::drop(). - See IRefCounted::drop() for more information. */ - virtual IAudioStream* createAudioStream(IFileReader* file) = 0; -}; - - -} // end namespace irrklang - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_AUDIO_STREAM_LOADER_H_INCLUDED__ +#define __I_IRRKLANG_AUDIO_STREAM_LOADER_H_INCLUDED__ + +#include "ik_IRefCounted.h" +#include "ik_IFileReader.h" + +namespace irrklang +{ + +class IAudioStream; + +//! Class which is able to create an audio file stream from a file. +class IAudioStreamLoader : public IRefCounted +{ +public: + + //! destructor + virtual ~IAudioStreamLoader() {}; + + //! Returns true if the file maybe is able to be loaded by this class. + /** This decision should be based only on the file extension (e.g. ".wav"). The given + filename string is guaranteed to be lower case. */ + virtual bool isALoadableFileExtension(const ik_c8* fileName) = 0; + + //! Creates an audio file input stream from a file + /** \return Pointer to the created audio stream. Returns 0 if loading failed. + If you no longer need the stream, you should call IAudioFileStream::drop(). + See IRefCounted::drop() for more information. */ + virtual IAudioStream* createAudioStream(IFileReader* file) = 0; +}; + + +} // end namespace irrklang + +#endif + diff --git a/src/dep/include/irrklang/ik_IFileFactory.h b/src/dep/include/irrklang/ik_IFileFactory.h index e6af0fa..1dfafb4 100644 --- a/src/dep/include/irrklang/ik_IFileFactory.h +++ b/src/dep/include/irrklang/ik_IFileFactory.h @@ -1,41 +1,41 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_FILE_FACTORY_H_INCLUDED__ -#define __I_IRRKLANG_FILE_FACTORY_H_INCLUDED__ - -#include "ik_IRefCounted.h" - -namespace irrklang -{ - class IFileReader; - - //! Interface to overwrite file access in irrKlang. - /** Derive your own class from IFileFactory, overwrite the createFileReader() - method and return your own implemented IFileReader to overwrite file access of irrKlang. - Use ISoundEngine::addFileFactory() to let irrKlang know about your class. - Example code can be found in the tutorial 04.OverrideFileAccess. - */ - class IFileFactory : public virtual IRefCounted - { - public: - - virtual ~IFileFactory() {}; - - //! Opens a file for read access. - /** Derive your own class from IFileFactory, overwrite this - method and return your own implemented IFileReader to overwrite file access of irrKlang. - Use ISoundEngine::addFileFactory() to let irrKlang know about your class. - Example code can be found in the tutorial 04.OverrideFileAccess. - \param filename Name of file to open. - \return Returns a pointer to the created file interface. - The returned pointer should be dropped when no longer needed. - See IRefCounted::drop() for more information. Returns 0 if file cannot be opened. */ - virtual IFileReader* createFileReader(const ik_c8* filename) = 0; - }; - -} // end namespace irrklang - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_FILE_FACTORY_H_INCLUDED__ +#define __I_IRRKLANG_FILE_FACTORY_H_INCLUDED__ + +#include "ik_IRefCounted.h" + +namespace irrklang +{ + class IFileReader; + + //! Interface to overwrite file access in irrKlang. + /** Derive your own class from IFileFactory, overwrite the createFileReader() + method and return your own implemented IFileReader to overwrite file access of irrKlang. + Use ISoundEngine::addFileFactory() to let irrKlang know about your class. + Example code can be found in the tutorial 04.OverrideFileAccess. + */ + class IFileFactory : public virtual IRefCounted + { + public: + + virtual ~IFileFactory() {}; + + //! Opens a file for read access. + /** Derive your own class from IFileFactory, overwrite this + method and return your own implemented IFileReader to overwrite file access of irrKlang. + Use ISoundEngine::addFileFactory() to let irrKlang know about your class. + Example code can be found in the tutorial 04.OverrideFileAccess. + \param filename Name of file to open. + \return Returns a pointer to the created file interface. + The returned pointer should be dropped when no longer needed. + See IRefCounted::drop() for more information. Returns 0 if file cannot be opened. */ + virtual IFileReader* createFileReader(const ik_c8* filename) = 0; + }; + +} // end namespace irrklang + +#endif + diff --git a/src/dep/include/irrklang/ik_IFileReader.h b/src/dep/include/irrklang/ik_IFileReader.h index 8f25557..82156cf 100644 --- a/src/dep/include/irrklang/ik_IFileReader.h +++ b/src/dep/include/irrklang/ik_IFileReader.h @@ -1,50 +1,50 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_READ_FILE_H_INCLUDED__ -#define __I_IRRKLANG_READ_FILE_H_INCLUDED__ - -#include "ik_IRefCounted.h" - -namespace irrklang -{ - - //! Interface providing read acess to a file. - class IFileReader : public virtual IRefCounted - { - public: - - virtual ~IFileReader() {}; - - //! Reads an amount of bytes from the file. - //! \param buffer: Pointer to buffer where to read bytes will be written to. - //! \param sizeToRead: Amount of bytes to read from the file. - //! \return Returns how much bytes were read. - virtual ik_s32 read(void* buffer, ik_u32 sizeToRead) = 0; - - //! Changes position in file, returns true if successful. - //! \param finalPos: Destination position in the file. - //! \param relativeMovement: If set to true, the position in the file is - //! changed relative to current position. Otherwise the position is changed - //! from beginning of file. - //! \return Returns true if successful, otherwise false. - virtual bool seek(ik_s32 finalPos, bool relativeMovement = false) = 0; - - //! Returns size of file. - //! \return Returns the size of the file in bytes. - virtual ik_s32 getSize() = 0; - - //! Returns the current position in the file. - //! \return Returns the current position in the file in bytes. - virtual ik_s32 getPos() = 0; - - //! Returns name of file. - //! \return Returns the file name as zero terminated character string. - virtual const ik_c8* getFileName() = 0; - }; - -} // end namespace irrklang - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_READ_FILE_H_INCLUDED__ +#define __I_IRRKLANG_READ_FILE_H_INCLUDED__ + +#include "ik_IRefCounted.h" + +namespace irrklang +{ + + //! Interface providing read acess to a file. + class IFileReader : public virtual IRefCounted + { + public: + + virtual ~IFileReader() {}; + + //! Reads an amount of bytes from the file. + //! \param buffer: Pointer to buffer where to read bytes will be written to. + //! \param sizeToRead: Amount of bytes to read from the file. + //! \return Returns how much bytes were read. + virtual ik_s32 read(void* buffer, ik_u32 sizeToRead) = 0; + + //! Changes position in file, returns true if successful. + //! \param finalPos: Destination position in the file. + //! \param relativeMovement: If set to true, the position in the file is + //! changed relative to current position. Otherwise the position is changed + //! from beginning of file. + //! \return Returns true if successful, otherwise false. + virtual bool seek(ik_s32 finalPos, bool relativeMovement = false) = 0; + + //! Returns size of file. + //! \return Returns the size of the file in bytes. + virtual ik_s32 getSize() = 0; + + //! Returns the current position in the file. + //! \return Returns the current position in the file in bytes. + virtual ik_s32 getPos() = 0; + + //! Returns name of file. + //! \return Returns the file name as zero terminated character string. + virtual const ik_c8* getFileName() = 0; + }; + +} // end namespace irrklang + +#endif + diff --git a/src/dep/include/irrklang/ik_IRefCounted.h b/src/dep/include/irrklang/ik_IRefCounted.h index cfe2e05..0cc79d0 100644 --- a/src/dep/include/irrklang/ik_IRefCounted.h +++ b/src/dep/include/irrklang/ik_IRefCounted.h @@ -1,131 +1,119 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_IREFERENCE_COUNTED_H_INCLUDED__ -#define __I_IRRKLANG_IREFERENCE_COUNTED_H_INCLUDED__ - -#include "ik_irrKlangTypes.h" - -namespace irrklang -{ - //! Base class of most objects of the irrKlang. - /** This class provides reference counting through the methods grab() and drop(). - It also is able to store a debug string for every instance of an object. - Most objects of irrKlang are derived from IRefCounted, and so they are reference counted. - - When you create an object in irrKlang, calling a method - which starts with 'create', an object is created, and you get a pointer - to the new object. If you no longer need the object, you have - to call drop(). This will destroy the object, if grab() was not called - in another part of you program, because this part still needs the object. - Note, that you only need to call drop() to the object, if you created it, - and the method had a 'create' in it. - - A simple example: - - If you want to create a texture, you may want to call an imaginable method - IDriver::createTexture. You call - ITexture* texture = driver->createTexture(128, 128); - If you no longer need the texture, call texture->drop(). - - If you want to load a texture, you may want to call imaginable method - IDriver::loadTexture. You do this like - ITexture* texture = driver->loadTexture("example.jpg"); - You will not have to drop the pointer to the loaded texture, because - the name of the method does not start with 'create'. The texture - is stored somewhere by the driver. - */ - class IRefCounted - { - public: - - //! Constructor. - IRefCounted() - : ReferenceCounter(1) - { - } - - //! Destructor. - virtual ~IRefCounted() - { - } - - //! Grabs the object. Increments the reference counter by one. - //! Someone who calls grab() to an object, should later also call - //! drop() to it. If an object never gets as much drop() as grab() - //! calls, it will never be destroyed. - //! The IRefCounted class provides a basic reference counting mechanism - //! with its methods grab() and drop(). Most objects of irrklang - //! are derived from IRefCounted, and so they are reference counted. - //! - //! When you create an object in irrKlang, calling a method - //! which starts with 'create', an object is created, and you get a pointer - //! to the new object. If you no longer need the object, you have - //! to call drop(). This will destroy the object, if grab() was not called - //! in another part of you program, because this part still needs the object. - //! Note, that you only need to call drop() to the object, if you created it, - //! and the method had a 'create' in it. - //! - //! A simple example: - //! - //! If you want to create a texture, you may want to call an imaginable method - //! IDriver::createTexture. You call - //! ITexture* texture = driver->createTexture(128, 128); - //! If you no longer need the texture, call texture->drop(). - //! If you want to load a texture, you may want to call imaginable method - //! IDriver::loadTexture. You do this like - //! ITexture* texture = driver->loadTexture("example.jpg"); - //! You will not have to drop the pointer to the loaded texture, because - //! the name of the method does not start with 'create'. The texture - //! is stored somewhere by the driver. - void grab() { ++ReferenceCounter; } - - //! Drops the object. Decrements the reference counter by one. - //! Returns true, if the object was deleted. - //! The IRefCounted class provides a basic reference counting mechanism - //! with its methods grab() and drop(). Most objects of irrKlang - //! Engine are derived from IRefCounted, and so they are reference counted. - //! - //! When you create an object in irrKlang, calling a method - //! which starts with 'create', an object is created, and you get a pointer - //! to the new object. If you no longer need the object, you have - //! to call drop(). This will destroy the object, if grab() was not called - //! in another part of you program, because this part still needs the object. - //! Note, that you only need to call drop() to the object, if you created it, - //! and the method had a 'create' in it. - //! - //! A simple example: - //! - //! If you want to create a texture, you may want to call an imaginable method - //! IDriver::createTexture. You call - //! ITexture* texture = driver->createTexture(128, 128); - //! If you no longer need the texture, call texture->drop(). - //! If you want to load a texture, you may want to call imaginable method - //! IDriver::loadTexture. You do this like - //! ITexture* texture = driver->loadTexture("example.jpg"); - //! You will not have to drop the pointer to the loaded texture, because - //! the name of the method does not start with 'create'. The texture - //! is stored somewhere by the driver. - bool drop() - { - --ReferenceCounter; - - if (!ReferenceCounter) - { - delete this; - return true; - } - - return false; - } - - private: - - ik_s32 ReferenceCounter; - }; - -} // end namespace irr - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_IREFERENCE_COUNTED_H_INCLUDED__ +#define __I_IRRKLANG_IREFERENCE_COUNTED_H_INCLUDED__ + +#include "ik_irrKlangTypes.h" + +namespace irrklang +{ + //! Base class of most objects of the irrKlang. + /** This class provides reference counting through the methods grab() and drop(). + It also is able to store a debug string for every instance of an object. + Most objects of irrKlang are derived from IRefCounted, and so they are reference counted. + + When you receive an object in irrKlang (for example an ISound using play2D() or + play3D()), and you no longer need the object, you have + to call drop(). This will destroy the object, if grab() was not called + in another part of you program, because this part still needs the object. + Note, that you only don't need to call drop() for all objects you receive, it + will be explicitely noted in the documentation. + + A simple example: + + If you want to play a sound, you may want to call the method + ISoundEngine::play2D. You call + ISound* mysound = engine->play2D("foobar.mp3", false, false true); + If you no longer need the sound interface, call mysound->drop(). The + sound may still play on after this because the engine still has a reference + to that sound, but you can be sure that it's memory will be released as soon + the sound is no longer used. + + If you want to add a sound source, you may want to call a method + ISoundEngine::addSoundSourceFromFile. You do this like + ISoundSource* mysource = engine->addSoundSourceFromFile("example.jpg"); + You will not have to drop the pointer to the source, because + sound sources are managed by the engine (it will live as long as the sound engine) and + the documentation says so. + */ + class IRefCounted + { + public: + + //! Constructor. + IRefCounted() + : ReferenceCounter(1) + { + } + + //! Destructor. + virtual ~IRefCounted() + { + } + + //! Grabs the object. Increments the reference counter by one. + //! Someone who calls grab() to an object, should later also call + //! drop() to it. If an object never gets as much drop() as grab() + //! calls, it will never be destroyed. + //! The IRefCounted class provides a basic reference counting mechanism + //! with its methods grab() and drop(). Most objects of irrklang + //! are derived from IRefCounted, and so they are reference counted. + //! + //! When you receive an object in irrKlang (for example an ISound using play2D() or + //! play3D()), and you no longer need the object, you have + //! to call drop(). This will destroy the object, if grab() was not called + //! in another part of you program, because this part still needs the object. + //! Note, that you only don't need to call drop() for all objects you receive, it + //! will be explicitely noted in the documentation. + //! + //! A simple example: + //! + //! If you want to play a sound, you may want to call the method + //! ISoundEngine::play2D. You call + //! ISound* mysound = engine->play2D("foobar.mp3", false, false true); + //! If you no longer need the sound interface, call mysound->drop(). The + //! sound may still play on after this because the engine still has a reference + //! to that sound, but you can be sure that it's memory will be released as soon + //! the sound is no longer used. + void grab() { ++ReferenceCounter; } + + //! When you receive an object in irrKlang (for example an ISound using play2D() or + //! play3D()), and you no longer need the object, you have + //! to call drop(). This will destroy the object, if grab() was not called + //! in another part of you program, because this part still needs the object. + //! Note, that you only don't need to call drop() for all objects you receive, it + //! will be explicitely noted in the documentation. + //! + //! A simple example: + //! + //! If you want to play a sound, you may want to call the method + //! ISoundEngine::play2D. You call + //! ISound* mysound = engine->play2D("foobar.mp3", false, false true); + //! If you no longer need the sound interface, call mysound->drop(). The + //! sound may still play on after this because the engine still has a reference + //! to that sound, but you can be sure that it's memory will be released as soon + //! the sound is no longer used. + bool drop() + { + --ReferenceCounter; + + if (!ReferenceCounter) + { + delete this; + return true; + } + + return false; + } + + private: + + ik_s32 ReferenceCounter; + }; + +} // end namespace irr + +#endif + diff --git a/src/dep/include/irrklang/ik_ISound.h b/src/dep/include/irrklang/ik_ISound.h index f403d4d..e9b9f6d 100644 --- a/src/dep/include/irrklang/ik_ISound.h +++ b/src/dep/include/irrklang/ik_ISound.h @@ -1,193 +1,193 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_SOUND_H_INCLUDED__ -#define __I_IRRKLANG_SOUND_H_INCLUDED__ - -#include "ik_IVirtualRefCounted.h" -#include "ik_ISoundEffectControl.h" -#include "ik_vec3d.h" - - -namespace irrklang -{ - class ISoundSource; - class ISoundStopEventReceiver; - - //! Represents a sound which is currently played. - /** The sound can be stopped, its volume or pan changed, effects added/removed - and similar using this interface. - Creating sounds is done using ISoundEngine::play2D() or ISoundEngine::play3D(). - More informations about the source of a sound can be obtained from the ISoundSource - interface. */ - class ISound : public IVirtualRefCounted - { - public: - - //! returns source of the sound which stores the filename and other informations about that sound - /** \return Returns the sound source poitner of this sound. May return 0 if the sound source - has been removed.*/ - virtual ISoundSource* getSoundSource() = 0; - - //! returns if the sound is paused - virtual void setIsPaused( bool paused = true) = 0; - - //! returns if the sound is paused - virtual bool getIsPaused() = 0; - - //! Will stop the sound and free its resources. - /** If you just want to pause the sound, use setIsPaused(). - After calling stop(), isFinished() will usually return true. */ - virtual void stop() = 0; - - //! returns volume of the sound, a value between 0 (mute) and 1 (full volume). - /** (this volume gets multiplied with the master volume of the sound engine - and other parameters like distance to listener when played as 3d sound) */ - virtual ik_f32 getVolume() = 0; - - //! sets the volume of the sound, a value between 0 (mute) and 1 (full volume). - /** This volume gets multiplied with the master volume of the sound engine - and other parameters like distance to listener when played as 3d sound. */ - virtual void setVolume(ik_f32 volume) = 0; - - //! sets the pan of the sound. Takes a value between -1 and 1, 0 is center. - virtual void setPan(ik_f32 pan) = 0; - - //! returns the pan of the sound. Takes a value between -1 and 1, 0 is center. - virtual ik_f32 getPan() = 0; - - //! returns if the sound has been started to play looped - virtual bool isLooped() = 0; - - //! changes the loop mode of the sound. - /** If the sound is playing looped and it is changed to not-looped, then it - will stop playing after the loop has finished. - If it is not looped and changed to looped, the sound will start repeating to be - played when it reaches its end. - Invoking this method will not have an effect when the sound already has stopped. */ - virtual void setIsLooped(bool looped) = 0; - - //! returns if the sound has finished playing. - /** Don't mix this up with isPaused(). isFinished() returns if the sound has been - finished playing. If it has, is maybe already have been removed from the playing list of the - sound engine and calls to any other of the methods of ISound will not have any result. - If you call stop() to a playing sound will result that this function will return true - when invoked. */ - virtual bool isFinished() = 0; - - //! Sets the minimal distance if this is a 3D sound. - /** Changes the distance at which the 3D sound stops getting louder. This works - like this: As a listener approaches a 3D sound source, the sound gets louder. - Past a certain point, it is not reasonable for the volume to continue to increase. - Either the maximum (zero) has been reached, or the nature of the sound source - imposes a logical limit. This is the minimum distance for the sound source. - Similarly, the maximum distance for a sound source is the distance beyond - which the sound does not get any quieter. - The default minimum distance is 1, the default max distance is a huge number like 1000000000.0f. */ - virtual void setMinDistance(ik_f32 min) = 0; - - //! Returns the minimal distance if this is a 3D sound. - /** See setMinDistance() for details. */ - virtual ik_f32 getMinDistance() = 0; - - //! Sets the maximal distance if this is a 3D sound. - /** Changing this value is usually not necessary. Use setMinDistance() instead. - Don't change this value if you don't know what you are doing: This value causes the sound - to stop attenuating after it reaches the max distance. Most people think that this sets the - volume of the sound to 0 after this distance, but this is not true. Only change the - minimal distance (using for example setMinDistance()) to influence this. - The maximum distance for a sound source is the distance beyond which the sound does not get any quieter. - The default minimum distance is 1, the default max distance is a huge number like 1000000000.0f. */ - virtual void setMaxDistance(ik_f32 max) = 0; - - //! Returns the maximal distance if this is a 3D sound. - /** See setMaxDistance() for details. */ - virtual ik_f32 getMaxDistance() = 0; - - //! sets the position of the sound in 3d space - virtual void setPosition(vec3df position) = 0; - - //! returns the position of the sound in 3d space - virtual vec3df getPosition() = 0; - - //! sets the position of the sound in 3d space, needed for Doppler effects. - /** To use doppler effects use ISound::setVelocity to set a sounds velocity, - ISoundEngine::setListenerPosition() to set the listeners velocity and - ISoundEngine::setDopplerEffectParameters() to adjust two parameters influencing - the doppler effects intensity. */ - virtual void setVelocity(vec3df vel) = 0; - - //! returns the velocity of the sound in 3d space, needed for Doppler effects. - /** To use doppler effects use ISound::setVelocity to set a sounds velocity, - ISoundEngine::setListenerPosition() to set the listeners velocity and - ISoundEngine::setDopplerEffectParameters() to adjust two parameters influencing - the doppler effects intensity. */ - virtual vec3df getVelocity() = 0; - - //! returns the current play position of the sound in milliseconds. - /** \return Returns -1 if not implemented or possible for this sound for example - because it already has been stopped and freed internally or similar. */ - virtual ik_u32 getPlayPosition() = 0; - - //! sets the current play position of the sound in milliseconds. - /** \param pos Position in milliseconds. Must be between 0 and the value returned - by getPlayPosition(). - \return Returns true successful. False is returned for example if the sound already finished - playing and is stopped or the audio source is not seekable, for example if it - is an internet stream or a a file format not supporting seeking (a .MOD file for example). - A file can be tested if it can bee seeking using ISoundSource::getIsSeekingSupported(). */ - virtual bool setPlayPosition(ik_u32 pos) = 0; - - //! Sets the playback speed (frequency) of the sound. - /** Plays the sound at a higher or lower speed, increasing or decreasing its - frequency which makes it sound lower or higher. - Note that this feature is not available on all sound output drivers (it is on the - DirectSound drivers at least), and it does not work together with the - 'enableSoundEffects' parameter of ISoundEngine::play2D and ISoundEngine::play3D when - using DirectSound. - \param speed Factor of the speed increase or decrease. 2 is twice as fast, - 0.5 is only half as fast. The default is 1.0. - \return Returns true if sucessful, false if not. The current sound driver might not - support changing the playBack speed, or the sound was started with the - 'enableSoundEffects' parameter. */ - virtual bool setPlaybackSpeed(ik_f32 speed = 1.0f) = 0; - - //! Returns the playback speed set by setPlaybackSpeed(). Default: 1.0f. - /** See setPlaybackSpeed() for details */ - virtual ik_f32 getPlaybackSpeed() = 0; - - //! returns the play length of the sound in milliseconds. - /** Returns -1 if not known for this sound for example because its decoder - does not support length reporting or it is a file stream of unknown size. - Note: You can also use ISoundSource::getPlayLength() to get the length of - a sound without actually needing to play it. */ - virtual ik_u32 getPlayLength() = 0; - - //! Returns the sound effect control interface for this sound. - /** Sound effects such as Chorus, Distorsions, Echo, Reverb and similar can - be controlled using this. The interface pointer is only valid as long as the ISound pointer is valid. - If the ISound pointer gets dropped (IVirtualRefCounted::drop()), the ISoundEffects - may not be used any more. - \return Returns a pointer to the sound effects interface if available. The sound - has to be started via ISoundEngine::play2D() or ISoundEngine::play3D(), - with the flag enableSoundEffects=true, otherwise 0 will be returned. Note that - if the output driver does not support sound effects, 0 will be returned as well.*/ - virtual ISoundEffectControl* getSoundEffectControl() = 0; - - //! Sets the sound stop event receiver, an interface which gets called if a sound has finished playing. - /** This event is guaranteed to be called when the sound or sound stream is finished, - either because the sound reached its playback end, its sound source was removed, - ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. - There is an example on how to use events in irrklang at @ref events . - \param receiver Interface to a user implementation of the sound receiver. This interface - should be as long valid as the sound exists or another stop event receiver is set. - Set this to null to set no sound stop event receiver. - \param userData: A iser data pointer, can be null. */ - virtual void setSoundStopEventReceiver(ISoundStopEventReceiver* reciever, void* userData=0) = 0; - }; - -} // end namespace irrklang - - -#endif +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_SOUND_H_INCLUDED__ +#define __I_IRRKLANG_SOUND_H_INCLUDED__ + +#include "ik_IVirtualRefCounted.h" +#include "ik_ISoundEffectControl.h" +#include "ik_vec3d.h" + + +namespace irrklang +{ + class ISoundSource; + class ISoundStopEventReceiver; + + //! Represents a sound which is currently played. + /** The sound can be stopped, its volume or pan changed, effects added/removed + and similar using this interface. + Creating sounds is done using ISoundEngine::play2D() or ISoundEngine::play3D(). + More informations about the source of a sound can be obtained from the ISoundSource + interface. */ + class ISound : public IVirtualRefCounted + { + public: + + //! returns source of the sound which stores the filename and other informations about that sound + /** \return Returns the sound source poitner of this sound. May return 0 if the sound source + has been removed.*/ + virtual ISoundSource* getSoundSource() = 0; + + //! returns if the sound is paused + virtual void setIsPaused( bool paused = true) = 0; + + //! returns if the sound is paused + virtual bool getIsPaused() = 0; + + //! Will stop the sound and free its resources. + /** If you just want to pause the sound, use setIsPaused(). + After calling stop(), isFinished() will usually return true. */ + virtual void stop() = 0; + + //! returns volume of the sound, a value between 0 (mute) and 1 (full volume). + /** (this volume gets multiplied with the master volume of the sound engine + and other parameters like distance to listener when played as 3d sound) */ + virtual ik_f32 getVolume() = 0; + + //! sets the volume of the sound, a value between 0 (mute) and 1 (full volume). + /** This volume gets multiplied with the master volume of the sound engine + and other parameters like distance to listener when played as 3d sound. */ + virtual void setVolume(ik_f32 volume) = 0; + + //! sets the pan of the sound. Takes a value between -1 and 1, 0 is center. + virtual void setPan(ik_f32 pan) = 0; + + //! returns the pan of the sound. Takes a value between -1 and 1, 0 is center. + virtual ik_f32 getPan() = 0; + + //! returns if the sound has been started to play looped + virtual bool isLooped() = 0; + + //! changes the loop mode of the sound. + /** If the sound is playing looped and it is changed to not-looped, then it + will stop playing after the loop has finished. + If it is not looped and changed to looped, the sound will start repeating to be + played when it reaches its end. + Invoking this method will not have an effect when the sound already has stopped. */ + virtual void setIsLooped(bool looped) = 0; + + //! returns if the sound has finished playing. + /** Don't mix this up with isPaused(). isFinished() returns if the sound has been + finished playing. If it has, is maybe already have been removed from the playing list of the + sound engine and calls to any other of the methods of ISound will not have any result. + If you call stop() to a playing sound will result that this function will return true + when invoked. */ + virtual bool isFinished() = 0; + + //! Sets the minimal distance if this is a 3D sound. + /** Changes the distance at which the 3D sound stops getting louder. This works + like this: As a listener approaches a 3D sound source, the sound gets louder. + Past a certain point, it is not reasonable for the volume to continue to increase. + Either the maximum (zero) has been reached, or the nature of the sound source + imposes a logical limit. This is the minimum distance for the sound source. + Similarly, the maximum distance for a sound source is the distance beyond + which the sound does not get any quieter. + The default minimum distance is 1, the default max distance is a huge number like 1000000000.0f. */ + virtual void setMinDistance(ik_f32 min) = 0; + + //! Returns the minimal distance if this is a 3D sound. + /** See setMinDistance() for details. */ + virtual ik_f32 getMinDistance() = 0; + + //! Sets the maximal distance if this is a 3D sound. + /** Changing this value is usually not necessary. Use setMinDistance() instead. + Don't change this value if you don't know what you are doing: This value causes the sound + to stop attenuating after it reaches the max distance. Most people think that this sets the + volume of the sound to 0 after this distance, but this is not true. Only change the + minimal distance (using for example setMinDistance()) to influence this. + The maximum distance for a sound source is the distance beyond which the sound does not get any quieter. + The default minimum distance is 1, the default max distance is a huge number like 1000000000.0f. */ + virtual void setMaxDistance(ik_f32 max) = 0; + + //! Returns the maximal distance if this is a 3D sound. + /** See setMaxDistance() for details. */ + virtual ik_f32 getMaxDistance() = 0; + + //! sets the position of the sound in 3d space + virtual void setPosition(vec3df position) = 0; + + //! returns the position of the sound in 3d space + virtual vec3df getPosition() = 0; + + //! sets the position of the sound in 3d space, needed for Doppler effects. + /** To use doppler effects use ISound::setVelocity to set a sounds velocity, + ISoundEngine::setListenerPosition() to set the listeners velocity and + ISoundEngine::setDopplerEffectParameters() to adjust two parameters influencing + the doppler effects intensity. */ + virtual void setVelocity(vec3df vel) = 0; + + //! returns the velocity of the sound in 3d space, needed for Doppler effects. + /** To use doppler effects use ISound::setVelocity to set a sounds velocity, + ISoundEngine::setListenerPosition() to set the listeners velocity and + ISoundEngine::setDopplerEffectParameters() to adjust two parameters influencing + the doppler effects intensity. */ + virtual vec3df getVelocity() = 0; + + //! returns the current play position of the sound in milliseconds. + /** \return Returns -1 if not implemented or possible for this sound for example + because it already has been stopped and freed internally or similar. */ + virtual ik_u32 getPlayPosition() = 0; + + //! sets the current play position of the sound in milliseconds. + /** \param pos Position in milliseconds. Must be between 0 and the value returned + by getPlayPosition(). + \return Returns true successful. False is returned for example if the sound already finished + playing and is stopped or the audio source is not seekable, for example if it + is an internet stream or a a file format not supporting seeking (a .MOD file for example). + A file can be tested if it can bee seeking using ISoundSource::getIsSeekingSupported(). */ + virtual bool setPlayPosition(ik_u32 pos) = 0; + + //! Sets the playback speed (frequency) of the sound. + /** Plays the sound at a higher or lower speed, increasing or decreasing its + frequency which makes it sound lower or higher. + Note that this feature is not available on all sound output drivers (it is on the + DirectSound drivers at least), and it does not work together with the + 'enableSoundEffects' parameter of ISoundEngine::play2D and ISoundEngine::play3D when + using DirectSound. + \param speed Factor of the speed increase or decrease. 2 is twice as fast, + 0.5 is only half as fast. The default is 1.0. + \return Returns true if sucessful, false if not. The current sound driver might not + support changing the playBack speed, or the sound was started with the + 'enableSoundEffects' parameter. */ + virtual bool setPlaybackSpeed(ik_f32 speed = 1.0f) = 0; + + //! Returns the playback speed set by setPlaybackSpeed(). Default: 1.0f. + /** See setPlaybackSpeed() for details */ + virtual ik_f32 getPlaybackSpeed() = 0; + + //! returns the play length of the sound in milliseconds. + /** Returns -1 if not known for this sound for example because its decoder + does not support length reporting or it is a file stream of unknown size. + Note: You can also use ISoundSource::getPlayLength() to get the length of + a sound without actually needing to play it. */ + virtual ik_u32 getPlayLength() = 0; + + //! Returns the sound effect control interface for this sound. + /** Sound effects such as Chorus, Distorsions, Echo, Reverb and similar can + be controlled using this. The interface pointer is only valid as long as the ISound pointer is valid. + If the ISound pointer gets dropped (IVirtualRefCounted::drop()), the ISoundEffects + may not be used any more. + \return Returns a pointer to the sound effects interface if available. The sound + has to be started via ISoundEngine::play2D() or ISoundEngine::play3D(), + with the flag enableSoundEffects=true, otherwise 0 will be returned. Note that + if the output driver does not support sound effects, 0 will be returned as well.*/ + virtual ISoundEffectControl* getSoundEffectControl() = 0; + + //! Sets the sound stop event receiver, an interface which gets called if a sound has finished playing. + /** This event is guaranteed to be called when the sound or sound stream is finished, + either because the sound reached its playback end, its sound source was removed, + ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. + There is an example on how to use events in irrklang at @ref events . + \param receiver Interface to a user implementation of the sound receiver. This interface + should be as long valid as the sound exists or another stop event receiver is set. + Set this to null to set no sound stop event receiver. + \param userData: A iser data pointer, can be null. */ + virtual void setSoundStopEventReceiver(ISoundStopEventReceiver* reciever, void* userData=0) = 0; + }; + +} // end namespace irrklang + + +#endif diff --git a/src/dep/include/irrklang/ik_ISoundDeviceList.h b/src/dep/include/irrklang/ik_ISoundDeviceList.h index 75790ff..d9556c5 100644 --- a/src/dep/include/irrklang/ik_ISoundDeviceList.h +++ b/src/dep/include/irrklang/ik_ISoundDeviceList.h @@ -1,41 +1,41 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_SOUND_DEVICE_LIST_H_INCLUDED__ -#define __I_IRRKLANG_SOUND_DEVICE_LIST_H_INCLUDED__ - -#include "ik_IRefCounted.h" - -namespace irrklang -{ - -//! A list of sound devices for a sound driver. Use irrklang::createSoundDeviceList() to create this list. -/** The function createIrrKlangDevice() has a parameter 'deviceID' which takes the value returned by -ISoundDeviceList::getDeviceID() and uses that device then. -The list of devices in ISoundDeviceList usually also includes the default device which is the first -entry and has an empty deviceID string ("") and the description "default device". -There is some example code on how to use the ISoundDeviceList in @ref enumeratingDevices.*/ -class ISoundDeviceList : public IRefCounted -{ -public: - - //! Returns amount of enumerated devices in the list. - virtual ik_s32 getDeviceCount() = 0; - - //! Returns the ID of the device. Use this string to identify this device in createIrrKlangDevice(). - /** \param index Index of the device, a value between 0 and ISoundDeviceList::getDeviceCount()-1. - \return Returns a pointer to a string identifying the device. The string will only as long valid - as long as the ISoundDeviceList exists. */ - virtual const char* getDeviceID(ik_s32 index) = 0; - - //! Returns description of the device. - /** \param index Index of the device, a value between 0 and ISoundDeviceList::getDeviceCount()-1. */ - virtual const char* getDeviceDescription(ik_s32 index) = 0; -}; - - -} // end namespace irrklang - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_SOUND_DEVICE_LIST_H_INCLUDED__ +#define __I_IRRKLANG_SOUND_DEVICE_LIST_H_INCLUDED__ + +#include "ik_IRefCounted.h" + +namespace irrklang +{ + +//! A list of sound devices for a sound driver. Use irrklang::createSoundDeviceList() to create this list. +/** The function createIrrKlangDevice() has a parameter 'deviceID' which takes the value returned by +ISoundDeviceList::getDeviceID() and uses that device then. +The list of devices in ISoundDeviceList usually also includes the default device which is the first +entry and has an empty deviceID string ("") and the description "default device". +There is some example code on how to use the ISoundDeviceList in @ref enumeratingDevices.*/ +class ISoundDeviceList : public IRefCounted +{ +public: + + //! Returns amount of enumerated devices in the list. + virtual ik_s32 getDeviceCount() = 0; + + //! Returns the ID of the device. Use this string to identify this device in createIrrKlangDevice(). + /** \param index Index of the device, a value between 0 and ISoundDeviceList::getDeviceCount()-1. + \return Returns a pointer to a string identifying the device. The string will only as long valid + as long as the ISoundDeviceList exists. */ + virtual const char* getDeviceID(ik_s32 index) = 0; + + //! Returns description of the device. + /** \param index Index of the device, a value between 0 and ISoundDeviceList::getDeviceCount()-1. */ + virtual const char* getDeviceDescription(ik_s32 index) = 0; +}; + + +} // end namespace irrklang + +#endif + diff --git a/src/dep/include/irrklang/ik_ISoundEffectControl.h b/src/dep/include/irrklang/ik_ISoundEffectControl.h index 53a7c9f..35992ed 100644 --- a/src/dep/include/irrklang/ik_ISoundEffectControl.h +++ b/src/dep/include/irrklang/ik_ISoundEffectControl.h @@ -1,243 +1,243 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_SOUND_EFFECT_CONTROL_H_INCLUDED__ -#define __I_IRRKLANG_SOUND_EFFECT_CONTROL_H_INCLUDED__ - -#include "ik_IVirtualRefCounted.h" -#include "ik_vec3d.h" - - -namespace irrklang -{ - //! Interface to control the active sound effects (echo, reverb,...) of an ISound object, a playing sound. - /** Sound effects such as chorus, distorsions, echo, reverb and similar can - be controlled using this. An instance of this interface can be obtained via - ISound::getSoundEffectControl(). The sound containing this interface has to be started via - ISoundEngine::play2D() or ISoundEngine::play3D() with the flag enableSoundEffects=true, - otherwise no acccess to this interface will be available. - For the DirectSound driver, these are effects available since DirectSound8. For most - effects, sounds should have a sample rate of 44 khz and should be at least - 150 milli seconds long for optimal quality when using the DirectSound driver. - Note that the interface pointer is only valid as long as - the ISound pointer is valid. If the ISound pointer gets dropped (IVirtualRefCounted::drop()), - the ISoundEffects may not be used any more. */ - class ISoundEffectControl - { - public: - - //! Disables all active sound effects - virtual void disableAllEffects() = 0; - - //! Enables the chorus sound effect or adjusts its values. - /** Chorus is a voice-doubling effect created by echoing the - original sound with a slight delay and slightly modulating the delay of the echo. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param fWetDryMix Ratio of wet (processed) signal to dry (unprocessed) signal. Minimal Value:0, Maximal Value:100.0f; - \param fDepth Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Minimal Value:0, Maximal Value:100.0f; - \param fFeedback Percentage of output signal to feed back into the effect's input. Minimal Value:-99, Maximal Value:99.0f; - \param fFrequency Frequency of the LFO. Minimal Value:0, Maximal Value:10.0f; - \param sinusWaveForm True for sinus wave form, false for triangle. - \param fDelay Number of milliseconds the input is delayed before it is played back. Minimal Value:0, Maximal Value:20.0f; - \param lPhase Phase differential between left and right LFOs. Possible values: - -180, -90, 0, 90, 180 - \return Returns true if successful. */ - virtual bool enableChorusSoundEffect(ik_f32 fWetDryMix = 50, - ik_f32 fDepth = 10, - ik_f32 fFeedback = 25, - ik_f32 fFrequency = 1.1, - bool sinusWaveForm = true, - ik_f32 fDelay = 16, - ik_s32 lPhase = 90) = 0; - - //! removes the sound effect from the sound - virtual void disableChorusSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isChorusSoundEffectEnabled() = 0; - - //! Enables the Compressor sound effect or adjusts its values. - /** Compressor is a reduction in the fluctuation of a signal above a certain amplitude. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param fGain Output gain of signal after Compressor. Minimal Value:-60, Maximal Value:60.0f; - \param fAttack Time before Compressor reaches its full value. Minimal Value:0.01, Maximal Value:500.0f; - \param fRelease Speed at which Compressor is stopped after input drops below fThreshold. Minimal Value:50, Maximal Value:3000.0f; - \param fThreshold Point at which Compressor begins, in decibels. Minimal Value:-60, Maximal Value:0.0f; - \param fRatio Compressor ratio. Minimal Value:1, Maximal Value:100.0f; - \param fPredelay Time after lThreshold is reached before attack phase is started, in milliseconds. Minimal Value:0, Maximal Value:4.0f; - \return Returns true if successful. */ - virtual bool enableCompressorSoundEffect( ik_f32 fGain = 0, - ik_f32 fAttack = 10, - ik_f32 fRelease = 200, - ik_f32 fThreshold = -20, - ik_f32 fRatio = 3, - ik_f32 fPredelay = 4) = 0; - - //! removes the sound effect from the sound - virtual void disableCompressorSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isCompressorSoundEffectEnabled() = 0; - - //! Enables the Distortion sound effect or adjusts its values. - /** Distortion is achieved by adding harmonics to the signal in such a way that, - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - as the level increases, the top of the waveform becomes squared off or clipped. - \param fGain Amount of signal change after distortion. Minimal Value:-60, Maximal Value:0; - \param fEdge Percentage of distortion intensity. Minimal Value:0, Maximal Value:100; - \param fPostEQCenterFrequency Center frequency of harmonic content addition. Minimal Value:100, Maximal Value:8000; - \param fPostEQBandwidth Width of frequency band that determines range of harmonic content addition. Minimal Value:100, Maximal Value:8000; - \param fPreLowpassCutoff Filter cutoff for high-frequency harmonics attenuation. Minimal Value:100, Maximal Value:8000; - \return Returns true if successful. */ - virtual bool enableDistortionSoundEffect(ik_f32 fGain = -18, - ik_f32 fEdge = 15, - ik_f32 fPostEQCenterFrequency = 2400, - ik_f32 fPostEQBandwidth = 2400, - ik_f32 fPreLowpassCutoff = 8000) = 0; - - //! removes the sound effect from the sound - virtual void disableDistortionSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isDistortionSoundEffectEnabled() = 0; - - //! Enables the Echo sound effect or adjusts its values. - /** An echo effect causes an entire sound to be repeated after a fixed delay. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param fWetDryMix Ratio of wet (processed) signal to dry (unprocessed) signal. Minimal Value:0, Maximal Value:100.0f; - \param fFeedback Percentage of output fed back into input. Minimal Value:0, Maximal Value:100.0f; - \param fLeftDelay Delay for left channel, in milliseconds. Minimal Value:1, Maximal Value:2000.0f; - \param fRightDelay Delay for right channel, in milliseconds. Minimal Value:1, Maximal Value:2000.0f; - \param lPanDelay Value that specifies whether to swap left and right delays with each successive echo. Minimal Value:0, Maximal Value:1; - \return Returns true if successful. */ - virtual bool enableEchoSoundEffect(ik_f32 fWetDryMix = 50, - ik_f32 fFeedback = 50, - ik_f32 fLeftDelay = 500, - ik_f32 fRightDelay = 500, - ik_s32 lPanDelay = 0) = 0; - - //! removes the sound effect from the sound - virtual void disableEchoSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isEchoSoundEffectEnabled() = 0; - - //! Enables the Flanger sound effect or adjusts its values. - /** Flange is an echo effect in which the delay between the original - signal and its echo is very short and varies over time. The result is - sometimes referred to as a sweeping sound. The term flange originated - with the practice of grabbing the flanges of a tape reel to change the speed. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param fWetDryMix Ratio of wet (processed) signal to dry (unprocessed) signal. Minimal Value:0, Maximal Value:100.0f; - \param fDepth Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Minimal Value:0, Maximal Value:100.0f; - \param fFeedback Percentage of output signal to feed back into the effect's input. Minimal Value:-99, Maximal Value:99.0f; - \param fFrequency Frequency of the LFO. Minimal Value:0, Maximal Value:10.0f; - \param triangleWaveForm True for triangle wave form, false for square. - \param fDelay Number of milliseconds the input is delayed before it is played back. Minimal Value:0, Maximal Value:20.0f; - \param lPhase Phase differential between left and right LFOs. Possible values: - -180, -90, 0, 90, 180 - \return Returns true if successful. */ - virtual bool enableFlangerSoundEffect(ik_f32 fWetDryMix = 50, - ik_f32 fDepth = 100, - ik_f32 fFeedback = -50, - ik_f32 fFrequency = 0.25f, - bool triangleWaveForm = true, - ik_f32 fDelay = 2, - ik_s32 lPhase = 0) = 0; - - //! removes the sound effect from the sound - virtual void disableFlangerSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isFlangerSoundEffectEnabled() = 0; - - //! Enables the Gargle sound effect or adjusts its values. - /** The gargle effect modulates the amplitude of the signal. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param rateHz Rate of modulation, in Hertz. Minimal Value:1, Maximal Value:1000 - \param sinusWaveForm True for sinus wave form, false for triangle. - \return Returns true if successful. */ - virtual bool enableGargleSoundEffect(ik_s32 rateHz = 20, bool sinusWaveForm = true) = 0; - - //! removes the sound effect from the sound - virtual void disableGargleSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isGargleSoundEffectEnabled() = 0; - - //! Enables the Interactive 3D Level 2 reverb sound effect or adjusts its values. - /** An implementation of the listener properties in the I3DL2 specification. Source properties are not supported. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param lRoom Attenuation of the room effect, in millibels (mB). Interval: [-10000, 0] Default: -1000 mB - \param lRoomHF Attenuation of the room high-frequency effect. Interval: [-10000, 0] default: 0 mB - \param flRoomRolloffFactor Rolloff factor for the reflected signals. Interval: [0.0, 10.0] default: 0.0 - \param flDecayTime Decay time, in seconds. Interval: [0.1, 20.0] default: 1.49s - \param flDecayHFRatio Ratio of the decay time at high frequencies to the decay time at low frequencies. Interval: [0.1, 2.0] default: 0.83 - \param lReflections Attenuation of early reflections relative to lRoom. Interval: [-10000, 1000] default: -2602 mB - \param flReflectionsDelay Delay time of the first reflection relative to the direct path in seconds. Interval: [0.0, 0.3] default: 0.007 s - \param lReverb Attenuation of late reverberation relative to lRoom, in mB. Interval: [-10000, 2000] default: 200 mB - \param flReverbDelay Time limit between the early reflections and the late reverberation relative to the time of the first reflection. Interval: [0.0, 0.1] default: 0.011 s - \param flDiffusion Echo density in the late reverberation decay in percent. Interval: [0.0, 100.0] default: 100.0 % - \param flDensity Modal density in the late reverberation decay, in percent. Interval: [0.0, 100.0] default: 100.0 % - \param flHFReference Reference high frequency, in hertz. Interval: [20.0, 20000.0] default: 5000.0 Hz - \return Returns true if successful. */ - virtual bool enableI3DL2ReverbSoundEffect(ik_s32 lRoom = -1000, - ik_s32 lRoomHF = -100, - ik_f32 flRoomRolloffFactor = 0, - ik_f32 flDecayTime = 1.49f, - ik_f32 flDecayHFRatio = 0.83f, - ik_s32 lReflections = -2602, - ik_f32 flReflectionsDelay = 0.007f, - ik_s32 lReverb = 200, - ik_f32 flReverbDelay = 0.011f, - ik_f32 flDiffusion = 100.0f, - ik_f32 flDensity = 100.0f, - ik_f32 flHFReference = 5000.0f ) = 0; - - //! removes the sound effect from the sound - virtual void disableI3DL2ReverbSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isI3DL2ReverbSoundEffectEnabled() = 0; - - //! Enables the ParamEq sound effect or adjusts its values. - /** Parametric equalizer amplifies or attenuates signals of a given frequency. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param fCenter Center frequency, in hertz, The default value is 8000. Minimal Value:80, Maximal Value:16000.0f - \param fBandwidth Bandwidth, in semitones, The default value is 12. Minimal Value:1.0f, Maximal Value:36.0f - \param fGain Gain, default value is 0. Minimal Value:-15.0f, Maximal Value:15.0f - \return Returns true if successful. */ - virtual bool enableParamEqSoundEffect(ik_f32 fCenter = 8000, - ik_f32 fBandwidth = 12, - ik_f32 fGain = 0) = 0; - - //! removes the sound effect from the sound - virtual void disableParamEqSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isParamEqSoundEffectEnabled() = 0; - - //! Enables the Waves Reverb sound effect or adjusts its values. - /** \param fInGain Input gain of signal, in decibels (dB). Min/Max: [-96.0,0.0] Default: 0.0 dB. - If this sound effect is already enabled, calling this only modifies the parameters of the active effect. - \param fReverbMix Reverb mix, in dB. Min/Max: [-96.0,0.0] Default: 0.0 dB - \param fReverbTime Reverb time, in milliseconds. Min/Max: [0.001,3000.0] Default: 1000.0 ms - \param fHighFreqRTRatio High-frequency reverb time ratio. Min/Max: [0.001,0.999] Default: 0.001 - \return Returns true if successful. */ - virtual bool enableWavesReverbSoundEffect(ik_f32 fInGain = 0, - ik_f32 fReverbMix = 0, - ik_f32 fReverbTime = 1000, - ik_f32 fHighFreqRTRatio = 0.001f) = 0; - - //! removes the sound effect from the sound - virtual void disableWavesReverbSoundEffect() = 0; - - //! returns if the sound effect is active on the sound - virtual bool isWavesReverbSoundEffectEnabled() = 0; - }; - -} // end namespace irrklang - - -#endif +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_SOUND_EFFECT_CONTROL_H_INCLUDED__ +#define __I_IRRKLANG_SOUND_EFFECT_CONTROL_H_INCLUDED__ + +#include "ik_IVirtualRefCounted.h" +#include "ik_vec3d.h" + + +namespace irrklang +{ + //! Interface to control the active sound effects (echo, reverb,...) of an ISound object, a playing sound. + /** Sound effects such as chorus, distorsions, echo, reverb and similar can + be controlled using this. An instance of this interface can be obtained via + ISound::getSoundEffectControl(). The sound containing this interface has to be started via + ISoundEngine::play2D() or ISoundEngine::play3D() with the flag enableSoundEffects=true, + otherwise no acccess to this interface will be available. + For the DirectSound driver, these are effects available since DirectSound8. For most + effects, sounds should have a sample rate of 44 khz and should be at least + 150 milli seconds long for optimal quality when using the DirectSound driver. + Note that the interface pointer is only valid as long as + the ISound pointer is valid. If the ISound pointer gets dropped (IVirtualRefCounted::drop()), + the ISoundEffects may not be used any more. */ + class ISoundEffectControl + { + public: + + //! Disables all active sound effects + virtual void disableAllEffects() = 0; + + //! Enables the chorus sound effect or adjusts its values. + /** Chorus is a voice-doubling effect created by echoing the + original sound with a slight delay and slightly modulating the delay of the echo. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param fWetDryMix Ratio of wet (processed) signal to dry (unprocessed) signal. Minimal Value:0, Maximal Value:100.0f; + \param fDepth Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Minimal Value:0, Maximal Value:100.0f; + \param fFeedback Percentage of output signal to feed back into the effect's input. Minimal Value:-99, Maximal Value:99.0f; + \param fFrequency Frequency of the LFO. Minimal Value:0, Maximal Value:10.0f; + \param sinusWaveForm True for sinus wave form, false for triangle. + \param fDelay Number of milliseconds the input is delayed before it is played back. Minimal Value:0, Maximal Value:20.0f; + \param lPhase Phase differential between left and right LFOs. Possible values: + -180, -90, 0, 90, 180 + \return Returns true if successful. */ + virtual bool enableChorusSoundEffect(ik_f32 fWetDryMix = 50, + ik_f32 fDepth = 10, + ik_f32 fFeedback = 25, + ik_f32 fFrequency = 1.1, + bool sinusWaveForm = true, + ik_f32 fDelay = 16, + ik_s32 lPhase = 90) = 0; + + //! removes the sound effect from the sound + virtual void disableChorusSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isChorusSoundEffectEnabled() = 0; + + //! Enables the Compressor sound effect or adjusts its values. + /** Compressor is a reduction in the fluctuation of a signal above a certain amplitude. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param fGain Output gain of signal after Compressor. Minimal Value:-60, Maximal Value:60.0f; + \param fAttack Time before Compressor reaches its full value. Minimal Value:0.01, Maximal Value:500.0f; + \param fRelease Speed at which Compressor is stopped after input drops below fThreshold. Minimal Value:50, Maximal Value:3000.0f; + \param fThreshold Point at which Compressor begins, in decibels. Minimal Value:-60, Maximal Value:0.0f; + \param fRatio Compressor ratio. Minimal Value:1, Maximal Value:100.0f; + \param fPredelay Time after lThreshold is reached before attack phase is started, in milliseconds. Minimal Value:0, Maximal Value:4.0f; + \return Returns true if successful. */ + virtual bool enableCompressorSoundEffect( ik_f32 fGain = 0, + ik_f32 fAttack = 10, + ik_f32 fRelease = 200, + ik_f32 fThreshold = -20, + ik_f32 fRatio = 3, + ik_f32 fPredelay = 4) = 0; + + //! removes the sound effect from the sound + virtual void disableCompressorSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isCompressorSoundEffectEnabled() = 0; + + //! Enables the Distortion sound effect or adjusts its values. + /** Distortion is achieved by adding harmonics to the signal in such a way that, + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + as the level increases, the top of the waveform becomes squared off or clipped. + \param fGain Amount of signal change after distortion. Minimal Value:-60, Maximal Value:0; + \param fEdge Percentage of distortion intensity. Minimal Value:0, Maximal Value:100; + \param fPostEQCenterFrequency Center frequency of harmonic content addition. Minimal Value:100, Maximal Value:8000; + \param fPostEQBandwidth Width of frequency band that determines range of harmonic content addition. Minimal Value:100, Maximal Value:8000; + \param fPreLowpassCutoff Filter cutoff for high-frequency harmonics attenuation. Minimal Value:100, Maximal Value:8000; + \return Returns true if successful. */ + virtual bool enableDistortionSoundEffect(ik_f32 fGain = -18, + ik_f32 fEdge = 15, + ik_f32 fPostEQCenterFrequency = 2400, + ik_f32 fPostEQBandwidth = 2400, + ik_f32 fPreLowpassCutoff = 8000) = 0; + + //! removes the sound effect from the sound + virtual void disableDistortionSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isDistortionSoundEffectEnabled() = 0; + + //! Enables the Echo sound effect or adjusts its values. + /** An echo effect causes an entire sound to be repeated after a fixed delay. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param fWetDryMix Ratio of wet (processed) signal to dry (unprocessed) signal. Minimal Value:0, Maximal Value:100.0f; + \param fFeedback Percentage of output fed back into input. Minimal Value:0, Maximal Value:100.0f; + \param fLeftDelay Delay for left channel, in milliseconds. Minimal Value:1, Maximal Value:2000.0f; + \param fRightDelay Delay for right channel, in milliseconds. Minimal Value:1, Maximal Value:2000.0f; + \param lPanDelay Value that specifies whether to swap left and right delays with each successive echo. Minimal Value:0, Maximal Value:1; + \return Returns true if successful. */ + virtual bool enableEchoSoundEffect(ik_f32 fWetDryMix = 50, + ik_f32 fFeedback = 50, + ik_f32 fLeftDelay = 500, + ik_f32 fRightDelay = 500, + ik_s32 lPanDelay = 0) = 0; + + //! removes the sound effect from the sound + virtual void disableEchoSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isEchoSoundEffectEnabled() = 0; + + //! Enables the Flanger sound effect or adjusts its values. + /** Flange is an echo effect in which the delay between the original + signal and its echo is very short and varies over time. The result is + sometimes referred to as a sweeping sound. The term flange originated + with the practice of grabbing the flanges of a tape reel to change the speed. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param fWetDryMix Ratio of wet (processed) signal to dry (unprocessed) signal. Minimal Value:0, Maximal Value:100.0f; + \param fDepth Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Minimal Value:0, Maximal Value:100.0f; + \param fFeedback Percentage of output signal to feed back into the effect's input. Minimal Value:-99, Maximal Value:99.0f; + \param fFrequency Frequency of the LFO. Minimal Value:0, Maximal Value:10.0f; + \param triangleWaveForm True for triangle wave form, false for square. + \param fDelay Number of milliseconds the input is delayed before it is played back. Minimal Value:0, Maximal Value:20.0f; + \param lPhase Phase differential between left and right LFOs. Possible values: + -180, -90, 0, 90, 180 + \return Returns true if successful. */ + virtual bool enableFlangerSoundEffect(ik_f32 fWetDryMix = 50, + ik_f32 fDepth = 100, + ik_f32 fFeedback = -50, + ik_f32 fFrequency = 0.25f, + bool triangleWaveForm = true, + ik_f32 fDelay = 2, + ik_s32 lPhase = 0) = 0; + + //! removes the sound effect from the sound + virtual void disableFlangerSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isFlangerSoundEffectEnabled() = 0; + + //! Enables the Gargle sound effect or adjusts its values. + /** The gargle effect modulates the amplitude of the signal. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param rateHz Rate of modulation, in Hertz. Minimal Value:1, Maximal Value:1000 + \param sinusWaveForm True for sinus wave form, false for triangle. + \return Returns true if successful. */ + virtual bool enableGargleSoundEffect(ik_s32 rateHz = 20, bool sinusWaveForm = true) = 0; + + //! removes the sound effect from the sound + virtual void disableGargleSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isGargleSoundEffectEnabled() = 0; + + //! Enables the Interactive 3D Level 2 reverb sound effect or adjusts its values. + /** An implementation of the listener properties in the I3DL2 specification. Source properties are not supported. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param lRoom Attenuation of the room effect, in millibels (mB). Interval: [-10000, 0] Default: -1000 mB + \param lRoomHF Attenuation of the room high-frequency effect. Interval: [-10000, 0] default: 0 mB + \param flRoomRolloffFactor Rolloff factor for the reflected signals. Interval: [0.0, 10.0] default: 0.0 + \param flDecayTime Decay time, in seconds. Interval: [0.1, 20.0] default: 1.49s + \param flDecayHFRatio Ratio of the decay time at high frequencies to the decay time at low frequencies. Interval: [0.1, 2.0] default: 0.83 + \param lReflections Attenuation of early reflections relative to lRoom. Interval: [-10000, 1000] default: -2602 mB + \param flReflectionsDelay Delay time of the first reflection relative to the direct path in seconds. Interval: [0.0, 0.3] default: 0.007 s + \param lReverb Attenuation of late reverberation relative to lRoom, in mB. Interval: [-10000, 2000] default: 200 mB + \param flReverbDelay Time limit between the early reflections and the late reverberation relative to the time of the first reflection. Interval: [0.0, 0.1] default: 0.011 s + \param flDiffusion Echo density in the late reverberation decay in percent. Interval: [0.0, 100.0] default: 100.0 % + \param flDensity Modal density in the late reverberation decay, in percent. Interval: [0.0, 100.0] default: 100.0 % + \param flHFReference Reference high frequency, in hertz. Interval: [20.0, 20000.0] default: 5000.0 Hz + \return Returns true if successful. */ + virtual bool enableI3DL2ReverbSoundEffect(ik_s32 lRoom = -1000, + ik_s32 lRoomHF = -100, + ik_f32 flRoomRolloffFactor = 0, + ik_f32 flDecayTime = 1.49f, + ik_f32 flDecayHFRatio = 0.83f, + ik_s32 lReflections = -2602, + ik_f32 flReflectionsDelay = 0.007f, + ik_s32 lReverb = 200, + ik_f32 flReverbDelay = 0.011f, + ik_f32 flDiffusion = 100.0f, + ik_f32 flDensity = 100.0f, + ik_f32 flHFReference = 5000.0f ) = 0; + + //! removes the sound effect from the sound + virtual void disableI3DL2ReverbSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isI3DL2ReverbSoundEffectEnabled() = 0; + + //! Enables the ParamEq sound effect or adjusts its values. + /** Parametric equalizer amplifies or attenuates signals of a given frequency. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param fCenter Center frequency, in hertz, The default value is 8000. Minimal Value:80, Maximal Value:16000.0f + \param fBandwidth Bandwidth, in semitones, The default value is 12. Minimal Value:1.0f, Maximal Value:36.0f + \param fGain Gain, default value is 0. Minimal Value:-15.0f, Maximal Value:15.0f + \return Returns true if successful. */ + virtual bool enableParamEqSoundEffect(ik_f32 fCenter = 8000, + ik_f32 fBandwidth = 12, + ik_f32 fGain = 0) = 0; + + //! removes the sound effect from the sound + virtual void disableParamEqSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isParamEqSoundEffectEnabled() = 0; + + //! Enables the Waves Reverb sound effect or adjusts its values. + /** \param fInGain Input gain of signal, in decibels (dB). Min/Max: [-96.0,0.0] Default: 0.0 dB. + If this sound effect is already enabled, calling this only modifies the parameters of the active effect. + \param fReverbMix Reverb mix, in dB. Min/Max: [-96.0,0.0] Default: 0.0 dB + \param fReverbTime Reverb time, in milliseconds. Min/Max: [0.001,3000.0] Default: 1000.0 ms + \param fHighFreqRTRatio High-frequency reverb time ratio. Min/Max: [0.001,0.999] Default: 0.001 + \return Returns true if successful. */ + virtual bool enableWavesReverbSoundEffect(ik_f32 fInGain = 0, + ik_f32 fReverbMix = 0, + ik_f32 fReverbTime = 1000, + ik_f32 fHighFreqRTRatio = 0.001f) = 0; + + //! removes the sound effect from the sound + virtual void disableWavesReverbSoundEffect() = 0; + + //! returns if the sound effect is active on the sound + virtual bool isWavesReverbSoundEffectEnabled() = 0; + }; + +} // end namespace irrklang + + +#endif diff --git a/src/dep/include/irrklang/ik_ISoundEngine.h b/src/dep/include/irrklang/ik_ISoundEngine.h index 9225086..d8c0f21 100644 --- a/src/dep/include/irrklang/ik_ISoundEngine.h +++ b/src/dep/include/irrklang/ik_ISoundEngine.h @@ -1,395 +1,431 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_SOUND_ENGINE_H_INCLUDED__ -#define __I_IRRKLANG_SOUND_ENGINE_H_INCLUDED__ - -#include "ik_IRefCounted.h" -#include "ik_vec3d.h" -#include "ik_ISoundSource.h" -#include "ik_ISound.h" -#include "ik_EStreamModes.h" -#include "ik_IFileFactory.h" - - -namespace irrklang -{ - class IAudioStreamLoader; - - //! Interface to the sound engine, for playing 3d and 2d sound and music. - /** This is the main interface of irrKlang. You usually would create this using - the createIrrKlangDevice() function. - */ - class ISoundEngine : public virtual irrklang::IRefCounted - { - public: - - //! returns the name of the sound driver, like 'ALSA' for the alsa device - /** Possible returned strings are "NULL", "ALSA", "CoreAudio", "winMM", - "DirectSound" and "DirectSound8". */ - virtual const char* getDriverName() = 0; - - //! loads a sound source (if not loaded already) from a file and plays it. - /** \param sourceFileName Filename of sound, like "sounds/test.wav" or "foobar.ogg". - \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to - ISound have no effect after such a non looped sound has been stopped automaticly. - \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing - parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to - modify some of the sound parameters and then call ISound::setPaused(false); - Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound - object anymore. See 'return' for details. - \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. - \param streamMode Specifies if the file should be streamed or loaded completely into memory for playing. - ESM_AUTO_DETECT sets this to autodetection. Note: if the sound has been loaded or played before into the - engine, this parameter has no effect. - \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, - reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). - Only enable if necessary. - \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or - 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, - you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this - will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or - 'enableSoundEffects' have been set to true, if the sound could not be played.*/ - virtual ISound* play2D(const char* soundFileName, - bool playLooped = false, - bool startPaused = false, - bool track = false, - E_STREAM_MODE streamMode = ESM_AUTO_DETECT, - bool enableSoundEffects = false) = 0; - - //! Plays a sound source as 2D sound with its default settings stored in ISoundSource. - /** An ISoundSource object will be created internally when playing a sound the first time, - or can be added with getSoundSource(). - \param source The sound source, specifiying sound file source and default settings for this file. - Use the other ISoundEngine::play2D() overloads if you want to specify a filename string instead of this. - \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to - ISound have no effect after such a non looped sound has been stopped automaticly. - \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing - parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to - modify some of the sound parameters and then call ISound::setPaused(false); - Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound - object anymore. See 'return' for details. - \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. - \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, - reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). - Only enable if necessary. - \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or - 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, - you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this - will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or - 'enableSoundEffects' have been set to true, if the sound could not be played.*/ - virtual ISound* play2D(ISoundSource* source, - bool playLooped = false, - bool startPaused = false, - bool track = false, - bool enableSoundEffects = false) = 0; - - //! Loads a sound source (if not loaded already) from a file and plays it as 3D sound. - /** There is some example code on how to work with 3D sound at @ref sound3d. - \param sourceFileName Filename of sound, like "sounds/test.wav" or "foobar.ogg". - \param pos Position of the 3D sound. - \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to - ISound have no effect after such a non looped sound has been stopped automaticly. - \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing - parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to - modify some of the sound parameters and then call ISound::setPaused(false); - Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound - object anymore. See 'return' for details. - \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. - \param streamMode Specifies if the file should be streamed or loaded completely into memory for playing. - ESM_AUTO_DETECT sets this to autodetection. Note: if the sound has been loaded or played before into the - engine, this parameter has no effect. - \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, - reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). - Only enable if necessary. - \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or - 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, - you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this - will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or - 'enableSoundEffects' have been set to true, if the sound could not be played.*/ - virtual ISound* play3D(const char* soundFileName, vec3df pos, - bool playLooped = false, - bool startPaused = false, - bool track = false, - E_STREAM_MODE streamMode = ESM_AUTO_DETECT, - bool enableSoundEffects = false) = 0; - - //! Plays a sound source as 3D sound with its default settings stored in ISoundSource. - /** An ISoundSource object will be created internally when playing a sound the first time, - or can be added with getSoundSource(). There is some example code on how to work with 3D sound @ref sound3d. - \param source The sound source, specifiying sound file source and default settings for this file. - Use the other ISoundEngine::play2D() overloads if you want to specify a filename string instead of this. - \param pos Position of the 3D sound. - \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to - ISound have no effect after such a non looped sound has been stopped automaticly. - \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing - parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to - modify some of the sound parameters and then call ISound::setPaused(false); - Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound - object anymore. See 'return' for details. - \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. - \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, - reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). - Only enable if necessary. - \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or - 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, - you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this - will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or - 'enableSoundEffects' have been set to true, if the sound could not be played.*/ - virtual ISound* play3D(ISoundSource* source, vec3df pos, - bool playLooped = false, - bool startPaused = false, - bool track = false, - bool enableSoundEffects = false) = 0; - - //! Stops all currently playing sounds. - virtual void stopAllSounds() = 0; - - //! Pauses or unpauses all currently playing sounds. - virtual void setAllSoundsPaused( bool bPaused = true ) = 0; - - //! Gets a sound source by sound name. Adds the sound source as file into the sound engine if not loaded already. - /** Please note: For performance reasons most ISoundEngine implementations will - not try to load the sound when calling this method, but only when play() is called - with this sound source as parameter. - \param addIfNotFound if 'true' adds the sound source to the list and returns the interface to it - if it cannot be found in the sound source list. If 'false', returns 0 if the sound - source is not in the list and does not modify the list. Default value: true. - \return Returns the sound source or 0 if not available. - Note: Don't call drop() to this pointer, it will be managed by irrKlang and - exist as long as you don't delete irrKlang or call removeSoundSource(). However, - you are free to call grab() if you want and drop() it then later of course. */ - virtual ISoundSource* getSoundSource(const ik_c8* soundName, bool addIfNotFound=true) = 0; - - //! Returns a sound source by index. - /** \param idx: Index of the loaded sound source, must by smaller than getSoundSourceCount(). - \return Returns the sound source or 0 if not available. - Note: Don't call drop() to this pointer, it will be managed by irrKlang and - exist as long as you don't delete irrKlang or call removeSoundSource(). However, - you are free to call grab() if you want and drop() it then later of course. */ - virtual ISoundSource* getSoundSource(ik_s32 index) = 0; - - //! Returns amount of loaded sound sources. - virtual ik_s32 getSoundSourceCount() = 0; - - //! Adds sound source into the sound engine as file. - /** \param fileName Name of the sound file (e.g. "sounds/something.mp3"). You can also use this - name when calling play3D() or play2D(). - \param mode Streaming mode for this sound source - \param preload If this flag is set to false (which is default) the sound engine will - not try to load the sound file when calling this method, but only when play() is called - with this sound source as parameter. Otherwise the sound will be preloaded. - \return Returns the pointer to the added sound source or 0 if not sucessful because for - example a sound already existed with that name. If not successful, the reason will be printed - into the log. Note: Don't call drop() to this pointer, it will be managed by irrKlang and - exist as long as you don't delete irrKlang or call removeSoundSource(). However, - you are free to call grab() if you want and drop() it then later of course. */ - virtual ISoundSource* addSoundSourceFromFile(const ik_c8* fileName, E_STREAM_MODE mode=ESM_AUTO_DETECT, - bool preload=false) = 0; - - //! Adds a sound source into the sound engine as memory source. - /** Note: This method only accepts a file (.wav, .ogg, etc) which is totally loaded into memory. - If you want to add a sound source from decoded plain PCM data in memory, use addSoundSourceFromPCMData() instead. - \param memory Pointer to the memory to be treated as loaded sound file. - \param sizeInBytes Size of the memory chunk, in bytes. - \param soundName Name of the virtual sound file (e.g. "sounds/something.mp3"). You can also use this - name when calling play3D() or play2D(). Hint: If you include the extension of the original file - like .ogg, .mp3 or .wav at the end of the filename, irrKlang will be able to decide better what - file format it is and might be able to start playback faster. - \param copyMemory If set to true which is default, the memory block is copied - and stored in the engine, after calling addSoundSourceFromMemory() the memory pointer can be deleted - savely. If set to true, the memory is not copied and the user takes the responsibility that - the memory block pointed to remains there as long as the sound engine or at least this sound - source exists. - \return Returns the pointer to the added sound source or 0 if not sucessful because for - example a sound already existed with that name. If not successful, the reason will be printed - into the log. */ - virtual ISoundSource* addSoundSourceFromMemory(void* memory, ik_s32 sizeInBytes, const ik_c8* soundName, - bool copyMemory=true) = 0; - - - //! Adds a sound source into the sound engine from plain PCM data in memory. - /** \param memory Pointer to the memory to be treated as loaded sound file. - \param sizeInBytes Size of the memory chunk, in bytes. - \param soundName Name of the virtual sound file (e.g. "sounds/something.mp3"). You can also use this - name when calling play3D() or play2D(). - \param copyMemory If set to true which is default, the memory block is copied - and stored in the engine, after calling addSoundSourceFromPCMData() the memory pointer can be deleted - savely. If set to true, the memory is not copied and the user takes the responsibility that - the memory block pointed to remains there as long as the sound engine or at least this sound - source exists. - \return Returns the pointer to the added sound source or 0 if not sucessful because for - example a sound already existed with that name. If not successful, the reason will be printed - into the log. */ - virtual ISoundSource* addSoundSourceFromPCMData(void* memory, ik_s32 sizeInBytes, - const ik_c8* soundName, SAudioStreamFormat format, - bool copyMemory=true) = 0; - - //! Adds a sound source as alias for an existing sound source, but with a different name or optional different default settings. - /** This is useful if you want to play multiple sounds but each sound isn't necessarily one single file. - Also useful if you want to or play the same sound using different names, volumes or min and max 3D distances. - \param baseSource The sound source where this sound source should be based on. This sound - source will use the baseSource as base to access the file and similar, but it will have its - own name and its own default settings. - \param soundName Name of the new sound source to be added. - \return Returns the pointer to the added sound source or 0 if not sucessful because for - example a sound already existed with that name. If not successful, the reason will be printed - into the log.*/ - virtual ISoundSource* addSoundSourceAlias(ISoundSource* baseSource, const ik_c8* soundName) = 0; - - //! Removes a sound source from the engine, freeing the memory it occupies. - /** This will also cause all currently playing sounds of this source to be stopped. - Also note that if the source has been removed successfully, the value returned - by getSoundSourceCount() will have been decreased by one. - Removing sound sources is only necessary if you know you won't use a lot of non-streamed - sounds again. Sound sources of streamed sounds do not cost a lot of memory.*/ - virtual void removeSoundSource(ISoundSource* source) = 0; - - //! Removes a sound source from the engine, freeing the memory it occupies. - /** This will also cause all currently playing sounds of this source to be stopped. - Also note that if the source has been removed successfully, the value returned - by getSoundSourceCount() will have been decreased by one. - Removing sound sources is only necessary if you know you won't use a lot of non-streamed - sounds again. Sound sources of streamed sounds do not cost a lot of memory. */ - virtual void removeSoundSource(const ik_c8* name) = 0; - - //! Removes all sound sources from the engine - /** This will also cause all sounds to be stopped. - Removing sound sources is only necessary if you know you won't use a lot of non-streamed - sounds again. Sound sources of streamed sounds do not cost a lot of memory. */ - virtual void removeAllSoundSources() = 0; - - //! Sets master sound volume. This value is multiplied with all sounds played. - /** \param volume 0 (silent) to 1.0f (full volume) */ - virtual void setSoundVolume(ik_f32 volume) = 0; - - //! Returns master sound volume. - /* A value between 0.0 and 1.0. Default is 1.0. Can be changed using setSoundVolume(). */ - virtual ik_f32 getSoundVolume() = 0; - - //! Sets the current listener 3d position. - /** When playing sounds in 3D, updating the position of the listener every frame should be - done using this function. - \param pos Position of the camera or listener. - \param lookdir Direction vector where the camera or listener is looking into. If you have a - camera position and a target 3d point where it is looking at, this would be cam->getTarget() - cam->getAbsolutePosition(). - \param velPerSecond The velocity per second describes the speed of the listener and - is only needed for doppler effects. - \param upvector Vector pointing 'up', so the engine can decide where is left and right. - This vector is usually (0,1,0).*/ - virtual void setListenerPosition(const vec3df& pos, - const vec3df& lookdir, - const vec3df& velPerSecond = vec3df(0,0,0), - const vec3df& upVector = vec3df(0,1,0)) = 0; - - //! Updates the audio engine. This should be called several times per frame if irrKlang was started in single thread mode. - /** This updates the 3d positions of the sounds as well as their volumes, effects, - streams and other stuff. Call this several times per frame (the more the better) if you - specified irrKlang to run single threaded. Otherwise it is not necessary to use this method. - This method is being called by the scene manager automaticly if you are using one, so - you might want to ignore this. */ - virtual void update() = 0; - - //! Returns if a sound with the specified name is currently playing. - virtual bool isCurrentlyPlaying(const char* soundName) = 0; - - //! Returns if a sound with the specified source is currently playing. - virtual bool isCurrentlyPlaying(ISoundSource* source) = 0; - - //! Registers a new audio stream loader in the sound engine. - /** Use this to enhance the audio engine to support other or new file formats. - To do this, implement your own IAudioStreamLoader interface and register it - with this method */ - virtual void registerAudioStreamLoader(IAudioStreamLoader* loader) = 0; - - //! Returns if irrKlang is running in the same thread as the application or is using multithreading. - /** This basicly returns the flag set by the user when creating the sound engine.*/ - virtual bool isMultiThreaded() const = 0; - - //! Adds a file factory to the sound engine, making it possible to override file access of the sound engine. - /** Derive your own class from IFileFactory, overwrite the createFileReader() - method and return your own implemented IFileReader to overwrite file access of irrKlang. */ - virtual void addFileFactory(IFileFactory* fileFactory) = 0; - - //! Sets the default minimal distance for 3D sounds. - /** This value influences how loud a sound is heard based on its distance. - See ISound::setMinDistance() for details about what the min distance is. - It is also possible to influence this default value for every sound file - using ISoundSource::setDefaultMinDistance(). - This method only influences the initial distance value of sounds. For changing the - distance after the sound has been started to play, use ISound::setMinDistance() and ISound::setMaxDistance(). - \param minDistance Default minimal distance for 3d sounds. The default value is 1.0f.*/ - virtual void setDefault3DSoundMinDistance(ik_f32 minDistance) = 0; - - //! Returns the default minimal distance for 3D sounds. - /** This value influences how loud a sound is heard based on its distance. - You can change it using setDefault3DSoundMinDistance(). - See ISound::setMinDistance() for details about what the min distance is. - It is also possible to influence this default value for every sound file - using ISoundSource::setDefaultMinDistance(). - \return Default minimal distance for 3d sounds. The default value is 1.0f. */ - virtual ik_f32 getDefault3DSoundMinDistance() = 0; - - //! Sets the default maximal distance for 3D sounds. - /** Changing this value is usually not necessary. Use setDefault3DSoundMinDistance() instead. - Don't change this value if you don't know what you are doing: This value causes the sound - to stop attenuating after it reaches the max distance. Most people think that this sets the - volume of the sound to 0 after this distance, but this is not true. Only change the - minimal distance (using for example setDefault3DSoundMinDistance()) to influence this. - See ISound::setMaxDistance() for details about what the max distance is. - It is also possible to influence this default value for every sound file - using ISoundSource::setDefaultMaxDistance(). - This method only influences the initial distance value of sounds. For changing the - distance after the sound has been started to play, use ISound::setMinDistance() and ISound::setMaxDistance(). - \param maxDistance Default maximal distance for 3d sounds. The default value is 1000000000.0f. */ - virtual void setDefault3DSoundMaxDistance(ik_f32 maxDistance) = 0; - - //! Returns the default maximal distance for 3D sounds. - /** This value influences how loud a sound is heard based on its distance. - You can change it using setDefault3DSoundmaxDistance(), but - changing this value is usually not necessary. This value causes the sound - to stop attenuating after it reaches the max distance. Most people think that this sets the - volume of the sound to 0 after this distance, but this is not true. Only change the - minimal distance (using for example setDefault3DSoundMinDistance()) to influence this. - See ISound::setMaxDistance() for details about what the max distance is. - It is also possible to influence this default value for every sound file - using ISoundSource::setDefaultMaxDistance(). - \return Default maximal distance for 3d sounds. The default value is 1000000000.0f. */ - virtual ik_f32 getDefault3DSoundMaxDistance() = 0; - - //! Sets a rolloff factor which influences the amount of attenuation that is applied to 3D sounds. - /** The rolloff factor can range from 0.0 to 10.0, where 0 is no rolloff. 1.0 is the default - rolloff factor set, the value which we also experience in the real world. A value of 2 would mean - twice the real-world rolloff. */ - virtual void setRolloffFactor(ik_f32 rolloff) = 0; - - //! Sets parameters affecting the doppler effect. - /** \param dopplerFactor is a value between 0 and 10 which multiplies the doppler - effect. Default value is 1.0, which is the real world doppler effect, and 10.0f - would be ten times the real world doppler effect. - \param distanceFactor is the number of meters in a vector unit. The default value - is 1.0. Doppler effects are calculated in meters per second, with this parameter, - this can be changed, all velocities and positions are influenced by this. If - the measurement should be in foot instead of meters, set this value to 0.3048f - for example.*/ - virtual void setDopplerEffectParameters(ik_f32 dopplerFactor=1.0f, ik_f32 distanceFactor=1.0f) = 0; - - //! Loads irrKlang plugins from a custom path. - /** Plugins usually are .dll, .so or .dylib - files named for example ikpMP3.dll (= short for irrKlangPluginMP3) which - make it possible to play back mp3 files. Plugins are being - loaded from the current working directory at startup of the sound engine - if the parameter ESEO_LOAD_PLUGINS is set (which it is by default), but - using this method, it is possible to load plugins from a custom path in addition. - \param path Path to the plugin directory, like "C:\games\somegamegame\irrklangplugins". - \return returns true if sucessful or fals if not, for example because the path could - not be found. */ - virtual bool loadPlugins(const ik_c8* path) = 0; - }; - - -} // end namespace irrklang - - -#endif +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_SOUND_ENGINE_H_INCLUDED__ +#define __I_IRRKLANG_SOUND_ENGINE_H_INCLUDED__ + +#include "ik_IRefCounted.h" +#include "ik_vec3d.h" +#include "ik_ISoundSource.h" +#include "ik_ISound.h" +#include "ik_EStreamModes.h" +#include "ik_IFileFactory.h" +#include "ik_ISoundMixedOutputReceiver.h" + + +namespace irrklang +{ + class IAudioStreamLoader; + struct SInternalAudioInterface; + + //! Interface to the sound engine, for playing 3d and 2d sound and music. + /** This is the main interface of irrKlang. You usually would create this using + the createIrrKlangDevice() function. + */ + class ISoundEngine : public virtual irrklang::IRefCounted + { + public: + + //! returns the name of the sound driver, like 'ALSA' for the alsa device + /** Possible returned strings are "NULL", "ALSA", "CoreAudio", "winMM", + "DirectSound" and "DirectSound8". */ + virtual const char* getDriverName() = 0; + + //! loads a sound source (if not loaded already) from a file and plays it. + /** \param sourceFileName Filename of sound, like "sounds/test.wav" or "foobar.ogg". + \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to + ISound have no effect after such a non looped sound has been stopped automaticly. + \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing + parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to + modify some of the sound parameters and then call ISound::setPaused(false); + Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound + object anymore. See 'return' for details. + \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. + \param streamMode Specifies if the file should be streamed or loaded completely into memory for playing. + ESM_AUTO_DETECT sets this to autodetection. Note: if the sound has been loaded or played before into the + engine, this parameter has no effect. + \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, + reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). + Only enable if necessary. + \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or + 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, + you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this + will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or + 'enableSoundEffects' have been set to true, if the sound could not be played.*/ + virtual ISound* play2D(const char* soundFileName, + bool playLooped = false, + bool startPaused = false, + bool track = false, + E_STREAM_MODE streamMode = ESM_AUTO_DETECT, + bool enableSoundEffects = false) = 0; + + //! Plays a sound source as 2D sound with its default settings stored in ISoundSource. + /** An ISoundSource object will be created internally when playing a sound the first time, + or can be added with getSoundSource(). + \param source The sound source, specifiying sound file source and default settings for this file. + Use the other ISoundEngine::play2D() overloads if you want to specify a filename string instead of this. + \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to + ISound have no effect after such a non looped sound has been stopped automaticly. + \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing + parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to + modify some of the sound parameters and then call ISound::setPaused(false); + Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound + object anymore. See 'return' for details. + \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. + \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, + reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). + Only enable if necessary. + \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or + 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, + you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this + will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or + 'enableSoundEffects' have been set to true, if the sound could not be played.*/ + virtual ISound* play2D(ISoundSource* source, + bool playLooped = false, + bool startPaused = false, + bool track = false, + bool enableSoundEffects = false) = 0; + + //! Loads a sound source (if not loaded already) from a file and plays it as 3D sound. + /** There is some example code on how to work with 3D sound at @ref sound3d. + \param sourceFileName Filename of sound, like "sounds/test.wav" or "foobar.ogg". + \param pos Position of the 3D sound. + \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to + ISound have no effect after such a non looped sound has been stopped automaticly. + \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing + parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to + modify some of the sound parameters and then call ISound::setPaused(false); + Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound + object anymore. See 'return' for details. + \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. + \param streamMode Specifies if the file should be streamed or loaded completely into memory for playing. + ESM_AUTO_DETECT sets this to autodetection. Note: if the sound has been loaded or played before into the + engine, this parameter has no effect. + \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, + reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). + Only enable if necessary. + \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or + 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, + you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this + will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or + 'enableSoundEffects' have been set to true, if the sound could not be played.*/ + virtual ISound* play3D(const char* soundFileName, vec3df pos, + bool playLooped = false, + bool startPaused = false, + bool track = false, + E_STREAM_MODE streamMode = ESM_AUTO_DETECT, + bool enableSoundEffects = false) = 0; + + //! Plays a sound source as 3D sound with its default settings stored in ISoundSource. + /** An ISoundSource object will be created internally when playing a sound the first time, + or can be added with getSoundSource(). There is some example code on how to work with 3D sound @ref sound3d. + \param source The sound source, specifiying sound file source and default settings for this file. + Use the other ISoundEngine::play2D() overloads if you want to specify a filename string instead of this. + \param pos Position of the 3D sound. + \param playLooped plays the sound in loop mode. If set to 'false', the sound is played once, then stopped and deleted from the internal playing list. Calls to + ISound have no effect after such a non looped sound has been stopped automaticly. + \param startPaused starts the sound paused. This implies that track=true. Use this if you want to modify some of the playing + parameters before the sound actually plays. Usually you would set this parameter to true, then use the ISound interface to + modify some of the sound parameters and then call ISound::setPaused(false); + Note: You need to call ISound::drop() when setting this parameter to true and you don't need the ISound + object anymore. See 'return' for details. + \param track Makes it possible to track the sound. Causes the method to return an ISound interface. See 'return' for details. + \param enableSoundEffects Makes it possible to use sound effects such as chorus, distorsions, echo, + reverb and similar for this sound. Sound effects can then be controlled via ISound::getSoundEffectControl(). + Only enable if necessary. + \return Only returns a pointer to an ISound if the parameters 'track', 'startPaused' or + 'enableSoundEffects' have been set to true. Note: if this method returns an ISound as result, + you HAVE to call ISound::drop() after you don't need the ISound interface anymore. Otherwise this + will cause memory waste. This method also may return 0 altough 'track', 'startPaused' or + 'enableSoundEffects' have been set to true, if the sound could not be played.*/ + virtual ISound* play3D(ISoundSource* source, vec3df pos, + bool playLooped = false, + bool startPaused = false, + bool track = false, + bool enableSoundEffects = false) = 0; + + //! Stops all currently playing sounds. + virtual void stopAllSounds() = 0; + + //! Pauses or unpauses all currently playing sounds. + virtual void setAllSoundsPaused( bool bPaused = true ) = 0; + + //! Gets a sound source by sound name. Adds the sound source as file into the sound engine if not loaded already. + /** Please note: For performance reasons most ISoundEngine implementations will + not try to load the sound when calling this method, but only when play() is called + with this sound source as parameter. + \param addIfNotFound if 'true' adds the sound source to the list and returns the interface to it + if it cannot be found in the sound source list. If 'false', returns 0 if the sound + source is not in the list and does not modify the list. Default value: true. + \return Returns the sound source or 0 if not available. + Note: Don't call drop() to this pointer, it will be managed by irrKlang and + exist as long as you don't delete irrKlang or call removeSoundSource(). However, + you are free to call grab() if you want and drop() it then later of course. */ + virtual ISoundSource* getSoundSource(const ik_c8* soundName, bool addIfNotFound=true) = 0; + + //! Returns a sound source by index. + /** \param idx: Index of the loaded sound source, must by smaller than getSoundSourceCount(). + \return Returns the sound source or 0 if not available. + Note: Don't call drop() to this pointer, it will be managed by irrKlang and + exist as long as you don't delete irrKlang or call removeSoundSource(). However, + you are free to call grab() if you want and drop() it then later of course. */ + virtual ISoundSource* getSoundSource(ik_s32 index) = 0; + + //! Returns amount of loaded sound sources. + virtual ik_s32 getSoundSourceCount() = 0; + + //! Adds sound source into the sound engine as file. + /** \param fileName Name of the sound file (e.g. "sounds/something.mp3"). You can also use this + name when calling play3D() or play2D(). + \param mode Streaming mode for this sound source + \param preload If this flag is set to false (which is default) the sound engine will + not try to load the sound file when calling this method, but only when play() is called + with this sound source as parameter. Otherwise the sound will be preloaded. + \return Returns the pointer to the added sound source or 0 if not sucessful because for + example a sound already existed with that name. If not successful, the reason will be printed + into the log. Note: Don't call drop() to this pointer, it will be managed by irrKlang and + exist as long as you don't delete irrKlang or call removeSoundSource(). However, + you are free to call grab() if you want and drop() it then later of course. */ + virtual ISoundSource* addSoundSourceFromFile(const ik_c8* fileName, E_STREAM_MODE mode=ESM_AUTO_DETECT, + bool preload=false) = 0; + + //! Adds a sound source into the sound engine as memory source. + /** Note: This method only accepts a file (.wav, .ogg, etc) which is totally loaded into memory. + If you want to add a sound source from decoded plain PCM data in memory, use addSoundSourceFromPCMData() instead. + \param memory Pointer to the memory to be treated as loaded sound file. + \param sizeInBytes Size of the memory chunk, in bytes. + \param soundName Name of the virtual sound file (e.g. "sounds/something.mp3"). You can also use this + name when calling play3D() or play2D(). Hint: If you include the extension of the original file + like .ogg, .mp3 or .wav at the end of the filename, irrKlang will be able to decide better what + file format it is and might be able to start playback faster. + \param copyMemory If set to true which is default, the memory block is copied + and stored in the engine, after calling addSoundSourceFromMemory() the memory pointer can be deleted + savely. If set to false, the memory is not copied and the user takes the responsibility that + the memory block pointed to remains there as long as the sound engine or at least this sound + source exists. + \return Returns the pointer to the added sound source or 0 if not sucessful because for + example a sound already existed with that name. If not successful, the reason will be printed + into the log. */ + virtual ISoundSource* addSoundSourceFromMemory(void* memory, ik_s32 sizeInBytes, const ik_c8* soundName, + bool copyMemory=true) = 0; + + + //! Adds a sound source into the sound engine from plain PCM data in memory. + /** \param memory Pointer to the memory to be treated as loaded sound file. + \param sizeInBytes Size of the memory chunk, in bytes. + \param soundName Name of the virtual sound file (e.g. "sounds/something.mp3"). You can also use this + name when calling play3D() or play2D(). + \param copyMemory If set to true which is default, the memory block is copied + and stored in the engine, after calling addSoundSourceFromPCMData() the memory pointer can be deleted + savely. If set to true, the memory is not copied and the user takes the responsibility that + the memory block pointed to remains there as long as the sound engine or at least this sound + source exists. + \return Returns the pointer to the added sound source or 0 if not sucessful because for + example a sound already existed with that name. If not successful, the reason will be printed + into the log. */ + virtual ISoundSource* addSoundSourceFromPCMData(void* memory, ik_s32 sizeInBytes, + const ik_c8* soundName, SAudioStreamFormat format, + bool copyMemory=true) = 0; + + //! Adds a sound source as alias for an existing sound source, but with a different name or optional different default settings. + /** This is useful if you want to play multiple sounds but each sound isn't necessarily one single file. + Also useful if you want to or play the same sound using different names, volumes or min and max 3D distances. + \param baseSource The sound source where this sound source should be based on. This sound + source will use the baseSource as base to access the file and similar, but it will have its + own name and its own default settings. + \param soundName Name of the new sound source to be added. + \return Returns the pointer to the added sound source or 0 if not sucessful because for + example a sound already existed with that name. If not successful, the reason will be printed + into the log.*/ + virtual ISoundSource* addSoundSourceAlias(ISoundSource* baseSource, const ik_c8* soundName) = 0; + + //! Removes a sound source from the engine, freeing the memory it occupies. + /** This will also cause all currently playing sounds of this source to be stopped. + Also note that if the source has been removed successfully, the value returned + by getSoundSourceCount() will have been decreased by one. + Removing sound sources is only necessary if you know you won't use a lot of non-streamed + sounds again. Sound sources of streamed sounds do not cost a lot of memory.*/ + virtual void removeSoundSource(ISoundSource* source) = 0; + + //! Removes a sound source from the engine, freeing the memory it occupies. + /** This will also cause all currently playing sounds of this source to be stopped. + Also note that if the source has been removed successfully, the value returned + by getSoundSourceCount() will have been decreased by one. + Removing sound sources is only necessary if you know you won't use a lot of non-streamed + sounds again. Sound sources of streamed sounds do not cost a lot of memory. */ + virtual void removeSoundSource(const ik_c8* name) = 0; + + //! Removes all sound sources from the engine + /** This will also cause all sounds to be stopped. + Removing sound sources is only necessary if you know you won't use a lot of non-streamed + sounds again. Sound sources of streamed sounds do not cost a lot of memory. */ + virtual void removeAllSoundSources() = 0; + + //! Sets master sound volume. This value is multiplied with all sounds played. + /** \param volume 0 (silent) to 1.0f (full volume) */ + virtual void setSoundVolume(ik_f32 volume) = 0; + + //! Returns master sound volume. + /* A value between 0.0 and 1.0. Default is 1.0. Can be changed using setSoundVolume(). */ + virtual ik_f32 getSoundVolume() = 0; + + //! Sets the current listener 3d position. + /** When playing sounds in 3D, updating the position of the listener every frame should be + done using this function. + \param pos Position of the camera or listener. + \param lookdir Direction vector where the camera or listener is looking into. If you have a + camera position and a target 3d point where it is looking at, this would be cam->getTarget() - cam->getAbsolutePosition(). + \param velPerSecond The velocity per second describes the speed of the listener and + is only needed for doppler effects. + \param upvector Vector pointing 'up', so the engine can decide where is left and right. + This vector is usually (0,1,0).*/ + virtual void setListenerPosition(const vec3df& pos, + const vec3df& lookdir, + const vec3df& velPerSecond = vec3df(0,0,0), + const vec3df& upVector = vec3df(0,1,0)) = 0; + + //! Updates the audio engine. This should be called several times per frame if irrKlang was started in single thread mode. + /** This updates the 3d positions of the sounds as well as their volumes, effects, + streams and other stuff. Call this several times per frame (the more the better) if you + specified irrKlang to run single threaded. Otherwise it is not necessary to use this method. + This method is being called by the scene manager automaticly if you are using one, so + you might want to ignore this. */ + virtual void update() = 0; + + //! Returns if a sound with the specified name is currently playing. + virtual bool isCurrentlyPlaying(const char* soundName) = 0; + + //! Returns if a sound with the specified source is currently playing. + virtual bool isCurrentlyPlaying(ISoundSource* source) = 0; + + //! Registers a new audio stream loader in the sound engine. + /** Use this to enhance the audio engine to support other or new file formats. + To do this, implement your own IAudioStreamLoader interface and register it + with this method */ + virtual void registerAudioStreamLoader(IAudioStreamLoader* loader) = 0; + + //! Returns if irrKlang is running in the same thread as the application or is using multithreading. + /** This basicly returns the flag set by the user when creating the sound engine.*/ + virtual bool isMultiThreaded() const = 0; + + //! Adds a file factory to the sound engine, making it possible to override file access of the sound engine. + /** Derive your own class from IFileFactory, overwrite the createFileReader() + method and return your own implemented IFileReader to overwrite file access of irrKlang. */ + virtual void addFileFactory(IFileFactory* fileFactory) = 0; + + //! Sets the default minimal distance for 3D sounds. + /** This value influences how loud a sound is heard based on its distance. + See ISound::setMinDistance() for details about what the min distance is. + It is also possible to influence this default value for every sound file + using ISoundSource::setDefaultMinDistance(). + This method only influences the initial distance value of sounds. For changing the + distance after the sound has been started to play, use ISound::setMinDistance() and ISound::setMaxDistance(). + \param minDistance Default minimal distance for 3d sounds. The default value is 1.0f.*/ + virtual void setDefault3DSoundMinDistance(ik_f32 minDistance) = 0; + + //! Returns the default minimal distance for 3D sounds. + /** This value influences how loud a sound is heard based on its distance. + You can change it using setDefault3DSoundMinDistance(). + See ISound::setMinDistance() for details about what the min distance is. + It is also possible to influence this default value for every sound file + using ISoundSource::setDefaultMinDistance(). + \return Default minimal distance for 3d sounds. The default value is 1.0f. */ + virtual ik_f32 getDefault3DSoundMinDistance() = 0; + + //! Sets the default maximal distance for 3D sounds. + /** Changing this value is usually not necessary. Use setDefault3DSoundMinDistance() instead. + Don't change this value if you don't know what you are doing: This value causes the sound + to stop attenuating after it reaches the max distance. Most people think that this sets the + volume of the sound to 0 after this distance, but this is not true. Only change the + minimal distance (using for example setDefault3DSoundMinDistance()) to influence this. + See ISound::setMaxDistance() for details about what the max distance is. + It is also possible to influence this default value for every sound file + using ISoundSource::setDefaultMaxDistance(). + This method only influences the initial distance value of sounds. For changing the + distance after the sound has been started to play, use ISound::setMinDistance() and ISound::setMaxDistance(). + \param maxDistance Default maximal distance for 3d sounds. The default value is 1000000000.0f. */ + virtual void setDefault3DSoundMaxDistance(ik_f32 maxDistance) = 0; + + //! Returns the default maximal distance for 3D sounds. + /** This value influences how loud a sound is heard based on its distance. + You can change it using setDefault3DSoundmaxDistance(), but + changing this value is usually not necessary. This value causes the sound + to stop attenuating after it reaches the max distance. Most people think that this sets the + volume of the sound to 0 after this distance, but this is not true. Only change the + minimal distance (using for example setDefault3DSoundMinDistance()) to influence this. + See ISound::setMaxDistance() for details about what the max distance is. + It is also possible to influence this default value for every sound file + using ISoundSource::setDefaultMaxDistance(). + \return Default maximal distance for 3d sounds. The default value is 1000000000.0f. */ + virtual ik_f32 getDefault3DSoundMaxDistance() = 0; + + //! Sets a rolloff factor which influences the amount of attenuation that is applied to 3D sounds. + /** The rolloff factor can range from 0.0 to 10.0, where 0 is no rolloff. 1.0 is the default + rolloff factor set, the value which we also experience in the real world. A value of 2 would mean + twice the real-world rolloff. */ + virtual void setRolloffFactor(ik_f32 rolloff) = 0; + + //! Sets parameters affecting the doppler effect. + /** \param dopplerFactor is a value between 0 and 10 which multiplies the doppler + effect. Default value is 1.0, which is the real world doppler effect, and 10.0f + would be ten times the real world doppler effect. + \param distanceFactor is the number of meters in a vector unit. The default value + is 1.0. Doppler effects are calculated in meters per second, with this parameter, + this can be changed, all velocities and positions are influenced by this. If + the measurement should be in foot instead of meters, set this value to 0.3048f + for example.*/ + virtual void setDopplerEffectParameters(ik_f32 dopplerFactor=1.0f, ik_f32 distanceFactor=1.0f) = 0; + + //! Loads irrKlang plugins from a custom path. + /** Plugins usually are .dll, .so or .dylib + files named for example ikpMP3.dll (= short for irrKlangPluginMP3) which + make it possible to play back mp3 files. Plugins are being + loaded from the current working directory at startup of the sound engine + if the parameter ESEO_LOAD_PLUGINS is set (which it is by default), but + using this method, it is possible to load plugins from a custom path in addition. + \param path Path to the plugin directory, like "C:\games\somegamegame\irrklangplugins". + \return returns true if sucessful or fals if not, for example because the path could + not be found. */ + virtual bool loadPlugins(const ik_c8* path) = 0; + + //! Returns a pointer to internal sound engine pointers, like the DirectSound interface. + /** Use this with caution. This is only exposed to make it possible for other libraries + such as Video playback packages to extend or use the sound driver irrklang uses. */ + virtual const SInternalAudioInterface& getInternalAudioInterface() = 0; + + //! Sets the OutputMixedDataReceiver, so you can receive the pure mixed output audio data while it is being played. + /** This can be used to store the sound output as .wav file or for creating a Oscillograph or similar. + This works only with software based audio drivers, that is ESOD_WIN_MM, ESOD_ALSA, and ESOD_CORE_AUDIO. + Returns true if sucessful and fals if the current audio driver doesn't support this feature. Set this to null + again once you don't need it anymore. */ + virtual bool setMixedDataOutputReceiver(ISoundMixedOutputReceiver* receiver) = 0; + }; + + + //! structure for returning pointers to the internal audio interface. + /** Use ISoundEngine::getInternalAudioInterface() to get this. */ + struct SInternalAudioInterface + { + //! IDirectSound interface, this is not null when using the ESOD_DIRECT_SOUND audio driver + void* pIDirectSound; + + //! IDirectSound8 interface, this is not null when using the ESOD_DIRECT_SOUND8 audio driver + void* pIDirectSound8; + + //! HWaveout interface, this is not null when using the ESOD_WIN_MM audio driver + void* pWinMM_HWaveOut; + + //! ALSA PCM Handle interface, this is not null when using the ESOD_ALSA audio driver + void* pALSA_SND_PCM; + + //! AudioDeviceID handle, this is not null when using the ESOD_CORE_AUDIO audio driver + ik_u32 pCoreAudioDeciceID; + }; + + + +} // end namespace irrklang + + +#endif diff --git a/src/dep/include/irrklang/ik_ISoundSource.h b/src/dep/include/irrklang/ik_ISoundSource.h index c3762ea..511c9a6 100644 --- a/src/dep/include/irrklang/ik_ISoundSource.h +++ b/src/dep/include/irrklang/ik_ISoundSource.h @@ -1,4 +1,4 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt +// Copyright (C) 2002-2009 Nikolaus Gebhardt // This file is part of the "irrKlang" library. // For conditions of distribution and use, see copyright notice in irrKlang.h @@ -146,7 +146,7 @@ namespace irrklang //! Returns the threshold size where irrKlang decides to force streaming a file independent of the user specified setting. /** The value is specified in uncompressed bytes and its default value is about one Megabyte. See setForcedStreamingThreshold() for details. */ - virtual ik_s32 getForcedStreamingForceThreshold() = 0; + virtual ik_s32 getForcedStreamingThreshold() = 0; //! Returns a pointer to the loaded and decoded sample data. /** \return Returns a pointer to the sample data. The data is provided in decoded PCM data. The diff --git a/src/dep/include/irrklang/ik_ISoundStopEventReceiver.h b/src/dep/include/irrklang/ik_ISoundStopEventReceiver.h index 360ad0f..06d3e2a 100644 --- a/src/dep/include/irrklang/ik_ISoundStopEventReceiver.h +++ b/src/dep/include/irrklang/ik_ISoundStopEventReceiver.h @@ -1,72 +1,72 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_SOUND_STOP_EVENT_RECEIVER_H_INCLUDED__ -#define __I_IRRKLANG_SOUND_STOP_EVENT_RECEIVER_H_INCLUDED__ - -#include "ik_IRefCounted.h" -#include "ik_SAudioStreamFormat.h" - - -namespace irrklang -{ - - -//! An enumeration listing all reasons for a fired sound stop event -enum E_STOP_EVENT_CAUSE -{ - //! The sound stop event was fired because the sound finished playing - ESEC_SOUND_FINISHED_PLAYING = 0, - - //! The sound stop event was fired because the sound was stopped by the user, calling ISound::stop(). - ESEC_SOUND_STOPPED_BY_USER, - - //! The sound stop event was fired because the source of the sound was removed, for example - //! because irrKlang was shut down or the user called ISoundEngine::removeSoundSource(). - ESEC_SOUND_STOPPED_BY_SOURCE_REMOVAL, - - //! This enumeration literal is never used, it only forces the compiler to - //! compile these enumeration values to 32 bit. - ESEC_FORCE_32_BIT = 0x7fffffff -}; - - -//! Interface to be implemented by the user, which recieves sound stop events. -/** The interface has only one method to be implemented by the user: OnSoundStopped(). -Implement this interface and set it via ISound::setSoundStopEventReceiver(). -The sound stop event is guaranteed to be called when a sound or sound stream is finished, -either because the sound reached its playback end, its sound source was removed, -ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. */ -class ISoundStopEventReceiver -{ -public: - - //! destructor - virtual ~ISoundStopEventReceiver() {}; - - //! Called when a sound has stopped playing. - /** This is the only method to be implemented by the user. - The sound stop event is guaranteed to be called when a sound or sound stream is finished, - either because the sound reached its playback end, its sound source was removed, - ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. - Please note: Sound events will occur in a different thread when the engine runs in - multi threaded mode (default). In single threaded mode, the event will happen while - the user thread is calling ISoundEngine::update(). - \param sound: Sound which has been stopped. - \param reason: The reason why the sound stop event was fired. Usually, this will be ESEC_SOUND_FINISHED_PLAYING. - When the sound was aborded by calling ISound::stop() or ISoundEngine::stopAllSounds();, this would be - ESEC_SOUND_STOPPED_BY_USER. If irrKlang was deleted or the sound source was removed, the value is - ESEC_SOUND_STOPPED_BY_SOURCE_REMOVAL. - \param userData: userData pointer set by the user when registering the interface - via ISound::setSoundStopEventReceiver(). */ - virtual void OnSoundStopped(ISound* sound, E_STOP_EVENT_CAUSE reason, void* userData) = 0; - -}; - - -} // end namespace irrklang - - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_SOUND_STOP_EVENT_RECEIVER_H_INCLUDED__ +#define __I_IRRKLANG_SOUND_STOP_EVENT_RECEIVER_H_INCLUDED__ + +#include "ik_IRefCounted.h" +#include "ik_SAudioStreamFormat.h" + + +namespace irrklang +{ + + +//! An enumeration listing all reasons for a fired sound stop event +enum E_STOP_EVENT_CAUSE +{ + //! The sound stop event was fired because the sound finished playing + ESEC_SOUND_FINISHED_PLAYING = 0, + + //! The sound stop event was fired because the sound was stopped by the user, calling ISound::stop(). + ESEC_SOUND_STOPPED_BY_USER, + + //! The sound stop event was fired because the source of the sound was removed, for example + //! because irrKlang was shut down or the user called ISoundEngine::removeSoundSource(). + ESEC_SOUND_STOPPED_BY_SOURCE_REMOVAL, + + //! This enumeration literal is never used, it only forces the compiler to + //! compile these enumeration values to 32 bit. + ESEC_FORCE_32_BIT = 0x7fffffff +}; + + +//! Interface to be implemented by the user, which recieves sound stop events. +/** The interface has only one method to be implemented by the user: OnSoundStopped(). +Implement this interface and set it via ISound::setSoundStopEventReceiver(). +The sound stop event is guaranteed to be called when a sound or sound stream is finished, +either because the sound reached its playback end, its sound source was removed, +ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. */ +class ISoundStopEventReceiver +{ +public: + + //! destructor + virtual ~ISoundStopEventReceiver() {}; + + //! Called when a sound has stopped playing. + /** This is the only method to be implemented by the user. + The sound stop event is guaranteed to be called when a sound or sound stream is finished, + either because the sound reached its playback end, its sound source was removed, + ISoundEngine::stopAllSounds() has been called or the whole engine was deleted. + Please note: Sound events will occur in a different thread when the engine runs in + multi threaded mode (default). In single threaded mode, the event will happen while + the user thread is calling ISoundEngine::update(). + \param sound: Sound which has been stopped. + \param reason: The reason why the sound stop event was fired. Usually, this will be ESEC_SOUND_FINISHED_PLAYING. + When the sound was aborded by calling ISound::stop() or ISoundEngine::stopAllSounds();, this would be + ESEC_SOUND_STOPPED_BY_USER. If irrKlang was deleted or the sound source was removed, the value is + ESEC_SOUND_STOPPED_BY_SOURCE_REMOVAL. + \param userData: userData pointer set by the user when registering the interface + via ISound::setSoundStopEventReceiver(). */ + virtual void OnSoundStopped(ISound* sound, E_STOP_EVENT_CAUSE reason, void* userData) = 0; + +}; + + +} // end namespace irrklang + + +#endif + diff --git a/src/dep/include/irrklang/ik_IVirtualRefCounted.h b/src/dep/include/irrklang/ik_IVirtualRefCounted.h index 711be23..1e85e82 100644 --- a/src/dep/include/irrklang/ik_IVirtualRefCounted.h +++ b/src/dep/include/irrklang/ik_IVirtualRefCounted.h @@ -1,48 +1,48 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __I_IRRKLANG_VIRTUAL_UNKNOWN_H_INCLUDED__ -#define __I_IRRKLANG_VIRTUAL_UNKNOWN_H_INCLUDED__ - -#include "ik_irrKlangTypes.h" - - -namespace irrklang -{ - - //! Reference counting base class for objects in the Irrlicht Engine similar to IRefCounted. - /** See IRefCounted for the basics of this class. - The difference to IRefCounted is that the class has to implement reference counting - for itself. - */ - class IVirtualRefCounted - { - public: - - //! Destructor. - virtual ~IVirtualRefCounted() - { - } - - //! Grabs the object. Increments the reference counter by one. - /** To be implemented by the derived class. If you don't want to - implement this, use the class IRefCounted instead. See IRefCounted::grab() for details - of this method. */ - virtual void grab() = 0; - - //! Drops the object. Decrements the reference counter by one. - /** To be implemented by the derived class. If you don't want to - implement this, use the class IRefCounted instead. See IRefCounted::grab() for details - of this method. */ - virtual bool drop() = 0; - }; - - - -} // end namespace irrklang - - - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __I_IRRKLANG_VIRTUAL_UNKNOWN_H_INCLUDED__ +#define __I_IRRKLANG_VIRTUAL_UNKNOWN_H_INCLUDED__ + +#include "ik_irrKlangTypes.h" + + +namespace irrklang +{ + + //! Reference counting base class for objects in the Irrlicht Engine similar to IRefCounted. + /** See IRefCounted for the basics of this class. + The difference to IRefCounted is that the class has to implement reference counting + for itself. + */ + class IVirtualRefCounted + { + public: + + //! Destructor. + virtual ~IVirtualRefCounted() + { + } + + //! Grabs the object. Increments the reference counter by one. + /** To be implemented by the derived class. If you don't want to + implement this, use the class IRefCounted instead. See IRefCounted::grab() for details + of this method. */ + virtual void grab() = 0; + + //! Drops the object. Decrements the reference counter by one. + /** To be implemented by the derived class. If you don't want to + implement this, use the class IRefCounted instead. See IRefCounted::grab() for details + of this method. */ + virtual bool drop() = 0; + }; + + + +} // end namespace irrklang + + + +#endif + diff --git a/src/dep/include/irrklang/ik_SAudioStreamFormat.h b/src/dep/include/irrklang/ik_SAudioStreamFormat.h index aa27349..6f42d21 100644 --- a/src/dep/include/irrklang/ik_SAudioStreamFormat.h +++ b/src/dep/include/irrklang/ik_SAudioStreamFormat.h @@ -1,71 +1,71 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __S_IRRKLANG_AUDIO_STREAM_FORMAT_H_INCLUDED__ -#define __S_IRRKLANG_AUDIO_STREAM_FORMAT_H_INCLUDED__ - -#include "ik_IRefCounted.h" - - -namespace irrklang -{ - - //! audio sample data format enumeration for supported formats - enum ESampleFormat - { - //! one unsigned byte (0;255) - ESF_U8, - - //! 16 bit, signed (-32k;32k) - ESF_S16 - }; - - - //! structure describing an audio stream format with helper functions - struct SAudioStreamFormat - { - //! channels, 1 for mono, 2 for stereo - ik_s32 ChannelCount; - - //! amount of frames in the sample data or stream. - /** If the stream has an unknown lenght, this is -1 */ - ik_s32 FrameCount; - - //! samples per second - ik_s32 SampleRate; - - //! format of the sample data - ESampleFormat SampleFormat; - - //! returns the size of a sample of the data described by the stream data in bytes - inline ik_s32 getSampleSize() const - { - return (SampleFormat == ESF_U8) ? 1 : 2; - } - - //! returns the frame size of the stream data in bytes - inline ik_s32 getFrameSize() const - { - return ChannelCount * getSampleSize(); - } - - //! returns the size of the sample data in bytes - /* Returns an invalid negative value when the stream has an unknown lenght */ - inline ik_s32 getSampleDataSize() const - { - return getFrameSize() * FrameCount; - } - - //! returns amount of bytes per second - inline ik_s32 getBytesPerSecond() const - { - return getFrameSize() * SampleRate; - } - }; - - -} // end namespace irrklang - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __S_IRRKLANG_AUDIO_STREAM_FORMAT_H_INCLUDED__ +#define __S_IRRKLANG_AUDIO_STREAM_FORMAT_H_INCLUDED__ + +#include "ik_IRefCounted.h" + + +namespace irrklang +{ + + //! audio sample data format enumeration for supported formats + enum ESampleFormat + { + //! one unsigned byte (0;255) + ESF_U8, + + //! 16 bit, signed (-32k;32k) + ESF_S16 + }; + + + //! structure describing an audio stream format with helper functions + struct SAudioStreamFormat + { + //! channels, 1 for mono, 2 for stereo + ik_s32 ChannelCount; + + //! amount of frames in the sample data or stream. + /** If the stream has an unknown lenght, this is -1 */ + ik_s32 FrameCount; + + //! samples per second + ik_s32 SampleRate; + + //! format of the sample data + ESampleFormat SampleFormat; + + //! returns the size of a sample of the data described by the stream data in bytes + inline ik_s32 getSampleSize() const + { + return (SampleFormat == ESF_U8) ? 1 : 2; + } + + //! returns the frame size of the stream data in bytes + inline ik_s32 getFrameSize() const + { + return ChannelCount * getSampleSize(); + } + + //! returns the size of the sample data in bytes + /* Returns an invalid negative value when the stream has an unknown lenght */ + inline ik_s32 getSampleDataSize() const + { + return getFrameSize() * FrameCount; + } + + //! returns amount of bytes per second + inline ik_s32 getBytesPerSecond() const + { + return getFrameSize() * SampleRate; + } + }; + + +} // end namespace irrklang + +#endif + diff --git a/src/dep/include/irrklang/ik_irrKlangTypes.h b/src/dep/include/irrklang/ik_irrKlangTypes.h index c3bc5db..1a454c8 100644 --- a/src/dep/include/irrklang/ik_irrKlangTypes.h +++ b/src/dep/include/irrklang/ik_irrKlangTypes.h @@ -1,78 +1,78 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __IRRKLANG_TYPES_H_INCLUDED__ -#define __IRRKLANG_TYPES_H_INCLUDED__ - - -namespace irrklang -{ - - //! 8 bit unsigned variable. - /** This is a typedef for unsigned char, it ensures portability of the engine. */ - typedef unsigned char ik_u8; - - //! 8 bit signed variable. - /** This is a typedef for signed char, it ensures portability of the engine. */ - typedef signed char ik_s8; - - //! 8 bit character variable. - /** This is a typedef for char, it ensures portability of the engine. */ - typedef char ik_c8; - - - - //! 16 bit unsigned variable. - /** This is a typedef for unsigned short, it ensures portability of the engine. */ - typedef unsigned short ik_u16; - - //! 16 bit signed variable. - /** This is a typedef for signed short, it ensures portability of the engine. */ - typedef signed short ik_s16; - - - - //! 32 bit unsigned variable. - /** This is a typedef for unsigned int, it ensures portability of the engine. */ - typedef unsigned int ik_u32; - - //! 32 bit signed variable. - /** This is a typedef for signed int, it ensures portability of the engine. */ - typedef signed int ik_s32; - - - - //! 32 bit floating point variable. - /** This is a typedef for float, it ensures portability of the engine. */ - typedef float ik_f32; - - //! 64 bit floating point variable. - /** This is a typedef for double, it ensures portability of the engine. */ - typedef double ik_f64; - - - - // some constants - - const ik_f32 IK_ROUNDING_ERROR_32 = 0.000001f; - const ik_f64 IK_PI64 = 3.1415926535897932384626433832795028841971693993751; - const ik_f32 IK_PI32 = 3.14159265359f; - const ik_f32 IK_RADTODEG = 180.0f / IK_PI32; - const ik_f32 IK_DEGTORAD = IK_PI32 / 180.0f; - const ik_f64 IK_RADTODEG64 = 180.0 / IK_PI64; - const ik_f64 IK_DEGTORAD64 = IK_PI64 / 180.0; - - //! returns if a float equals the other one, taking floating - //! point rounding errors into account - inline bool equalsfloat(const ik_f32 a, const ik_f32 b, const ik_f32 tolerance = IK_ROUNDING_ERROR_32) - { - return (a + tolerance > b) && (a - tolerance < b); - } - - -} // end namespace - - -#endif // __IRR_TYPES_H_INCLUDED__ - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __IRRKLANG_TYPES_H_INCLUDED__ +#define __IRRKLANG_TYPES_H_INCLUDED__ + + +namespace irrklang +{ + + //! 8 bit unsigned variable. + /** This is a typedef for unsigned char, it ensures portability of the engine. */ + typedef unsigned char ik_u8; + + //! 8 bit signed variable. + /** This is a typedef for signed char, it ensures portability of the engine. */ + typedef signed char ik_s8; + + //! 8 bit character variable. + /** This is a typedef for char, it ensures portability of the engine. */ + typedef char ik_c8; + + + + //! 16 bit unsigned variable. + /** This is a typedef for unsigned short, it ensures portability of the engine. */ + typedef unsigned short ik_u16; + + //! 16 bit signed variable. + /** This is a typedef for signed short, it ensures portability of the engine. */ + typedef signed short ik_s16; + + + + //! 32 bit unsigned variable. + /** This is a typedef for unsigned int, it ensures portability of the engine. */ + typedef unsigned int ik_u32; + + //! 32 bit signed variable. + /** This is a typedef for signed int, it ensures portability of the engine. */ + typedef signed int ik_s32; + + + + //! 32 bit floating point variable. + /** This is a typedef for float, it ensures portability of the engine. */ + typedef float ik_f32; + + //! 64 bit floating point variable. + /** This is a typedef for double, it ensures portability of the engine. */ + typedef double ik_f64; + + + + // some constants + + const ik_f32 IK_ROUNDING_ERROR_32 = 0.000001f; + const ik_f64 IK_PI64 = 3.1415926535897932384626433832795028841971693993751; + const ik_f32 IK_PI32 = 3.14159265359f; + const ik_f32 IK_RADTODEG = 180.0f / IK_PI32; + const ik_f32 IK_DEGTORAD = IK_PI32 / 180.0f; + const ik_f64 IK_RADTODEG64 = 180.0 / IK_PI64; + const ik_f64 IK_DEGTORAD64 = IK_PI64 / 180.0; + + //! returns if a float equals the other one, taking floating + //! point rounding errors into account + inline bool equalsfloat(const ik_f32 a, const ik_f32 b, const ik_f32 tolerance = IK_ROUNDING_ERROR_32) + { + return (a + tolerance > b) && (a - tolerance < b); + } + + +} // end namespace + + +#endif // __IRR_TYPES_H_INCLUDED__ + diff --git a/src/dep/include/irrklang/ik_vec3d.h b/src/dep/include/irrklang/ik_vec3d.h index bd18754..e1c97a3 100644 --- a/src/dep/include/irrklang/ik_vec3d.h +++ b/src/dep/include/irrklang/ik_vec3d.h @@ -1,261 +1,261 @@ -// Copyright (C) 2002-2008 Nikolaus Gebhardt -// This file is part of the "irrKlang" library. -// For conditions of distribution and use, see copyright notice in irrKlang.h - -#ifndef __IRR_IRRKLANG_VEC_3D_H_INCLUDED__ -#define __IRR_IRRKLANG_VEC_3D_H_INCLUDED__ - -#include -#include "ik_irrKlangTypes.h" - - -namespace irrklang -{ - - //! a 3d vector template class for representing vectors and points in 3d - template - class vec3d - { - public: - - vec3d(): X(0), Y(0), Z(0) {}; - vec3d(T nx, T ny, T nz) : X(nx), Y(ny), Z(nz) {}; - vec3d(const vec3d& other) :X(other.X), Y(other.Y), Z(other.Z) {}; - - //! constructor creating an irrklang vec3d from an irrlicht vector. - #ifdef __IRR_POINT_3D_H_INCLUDED__ - template - vec3d(const B& other) :X(other.X), Y(other.Y), Z(other.Z) {}; - #endif // __IRR_POINT_3D_H_INCLUDED__ - - // operators - - vec3d operator-() const { return vec3d(-X, -Y, -Z); } - - vec3d& operator=(const vec3d& other) { X = other.X; Y = other.Y; Z = other.Z; return *this; } - - vec3d operator+(const vec3d& other) const { return vec3d(X + other.X, Y + other.Y, Z + other.Z); } - vec3d& operator+=(const vec3d& other) { X+=other.X; Y+=other.Y; Z+=other.Z; return *this; } - - vec3d operator-(const vec3d& other) const { return vec3d(X - other.X, Y - other.Y, Z - other.Z); } - vec3d& operator-=(const vec3d& other) { X-=other.X; Y-=other.Y; Z-=other.Z; return *this; } - - vec3d operator*(const vec3d& other) const { return vec3d(X * other.X, Y * other.Y, Z * other.Z); } - vec3d& operator*=(const vec3d& other) { X*=other.X; Y*=other.Y; Z*=other.Z; return *this; } - vec3d operator*(const T v) const { return vec3d(X * v, Y * v, Z * v); } - vec3d& operator*=(const T v) { X*=v; Y*=v; Z*=v; return *this; } - - vec3d operator/(const vec3d& other) const { return vec3d(X / other.X, Y / other.Y, Z / other.Z); } - vec3d& operator/=(const vec3d& other) { X/=other.X; Y/=other.Y; Z/=other.Z; return *this; } - vec3d operator/(const T v) const { T i=(T)1.0/v; return vec3d(X * i, Y * i, Z * i); } - vec3d& operator/=(const T v) { T i=(T)1.0/v; X*=i; Y*=i; Z*=i; return *this; } - - bool operator<=(const vec3d&other) const { return X<=other.X && Y<=other.Y && Z<=other.Z;}; - bool operator>=(const vec3d&other) const { return X>=other.X && Y>=other.Y && Z>=other.Z;}; - - bool operator==(const vec3d& other) const { return other.X==X && other.Y==Y && other.Z==Z; } - bool operator!=(const vec3d& other) const { return other.X!=X || other.Y!=Y || other.Z!=Z; } - - // functions - - //! returns if this vector equalsfloat the other one, taking floating point rounding errors into account - bool equals(const vec3d& other) - { - return equalsfloat(X, other.X) && - equalsfloat(Y, other.Y) && - equalsfloat(Z, other.Z); - } - - void set(const T nx, const T ny, const T nz) {X=nx; Y=ny; Z=nz; } - void set(const vec3d& p) { X=p.X; Y=p.Y; Z=p.Z;} - - //! Returns length of the vector. - ik_f64 getLength() const { return sqrt(X*X + Y*Y + Z*Z); } - - //! Returns squared length of the vector. - /** This is useful because it is much faster then - getLength(). */ - ik_f64 getLengthSQ() const { return X*X + Y*Y + Z*Z; } - - //! Returns the dot product with another vector. - T dotProduct(const vec3d& other) const - { - return X*other.X + Y*other.Y + Z*other.Z; - } - - //! Returns distance from an other point. - /** Here, the vector is interpreted as point in 3 dimensional space. */ - ik_f64 getDistanceFrom(const vec3d& other) const - { - ik_f64 vx = X - other.X; ik_f64 vy = Y - other.Y; ik_f64 vz = Z - other.Z; - return sqrt(vx*vx + vy*vy + vz*vz); - } - - //! Returns squared distance from an other point. - /** Here, the vector is interpreted as point in 3 dimensional space. */ - ik_f32 getDistanceFromSQ(const vec3d& other) const - { - ik_f32 vx = X - other.X; ik_f32 vy = Y - other.Y; ik_f32 vz = Z - other.Z; - return (vx*vx + vy*vy + vz*vz); - } - - //! Calculates the cross product with another vector - vec3d crossProduct(const vec3d& p) const - { - return vec3d(Y * p.Z - Z * p.Y, Z * p.X - X * p.Z, X * p.Y - Y * p.X); - } - - //! Returns if this vector interpreted as a point is on a line between two other points. - /** It is assumed that the point is on the line. */ - bool isBetweenPoints(const vec3d& begin, const vec3d& end) const - { - ik_f32 f = (ik_f32)(end - begin).getLengthSQ(); - return (ik_f32)getDistanceFromSQ(begin) < f && - (ik_f32)getDistanceFromSQ(end) < f; - } - - //! Normalizes the vector. - vec3d& normalize() - { - T l = (T)getLength(); - if (l == 0) - return *this; - - l = (T)1.0 / l; - X *= l; - Y *= l; - Z *= l; - return *this; - } - - //! Sets the lenght of the vector to a new value - void setLength(T newlength) - { - normalize(); - *this *= newlength; - } - - //! Inverts the vector. - void invert() - { - X *= -1.0f; - Y *= -1.0f; - Z *= -1.0f; - } - - //! Rotates the vector by a specified number of degrees around the Y - //! axis and the specified center. - //! \param degrees: Number of degrees to rotate around the Y axis. - //! \param center: The center of the rotation. - void rotateXZBy(ik_f64 degrees, const vec3d& center) - { - degrees *= IK_DEGTORAD64; - T cs = (T)cos(degrees); - T sn = (T)sin(degrees); - X -= center.X; - Z -= center.Z; - set(X*cs - Z*sn, Y, X*sn + Z*cs); - X += center.X; - Z += center.Z; - } - - //! Rotates the vector by a specified number of degrees around the Z - //! axis and the specified center. - //! \param degrees: Number of degrees to rotate around the Z axis. - //! \param center: The center of the rotation. - void rotateXYBy(ik_f64 degrees, const vec3d& center) - { - degrees *= IK_DEGTORAD64; - T cs = (T)cos(degrees); - T sn = (T)sin(degrees); - X -= center.X; - Y -= center.Y; - set(X*cs - Y*sn, X*sn + Y*cs, Z); - X += center.X; - Y += center.Y; - } - - //! Rotates the vector by a specified number of degrees around the X - //! axis and the specified center. - //! \param degrees: Number of degrees to rotate around the X axis. - //! \param center: The center of the rotation. - void rotateYZBy(ik_f64 degrees, const vec3d& center) - { - degrees *= IK_DEGTORAD64; - T cs = (T)cos(degrees); - T sn = (T)sin(degrees); - Z -= center.Z; - Y -= center.Y; - set(X, Y*cs - Z*sn, Y*sn + Z*cs); - Z += center.Z; - Y += center.Y; - } - - //! Returns interpolated vector. - /** \param other: other vector to interpolate between - \param d: value between 0.0f and 1.0f. */ - vec3d getInterpolated(const vec3d& other, ik_f32 d) const - { - ik_f32 inv = 1.0f - d; - return vec3d(other.X*inv + X*d, - other.Y*inv + Y*d, - other.Z*inv + Z*d); - } - - //! Gets the Y and Z rotations of a vector. - /** Thanks to Arras on the Irrlicht forums to add this method. - \return A vector representing the rotation in degrees of - this vector. The Z component of the vector will always be 0. */ - vec3d getHorizontalAngle() - { - vec3d angle; - - angle.Y = (T)atan2(X, Z); - angle.Y *= (ik_f32)IK_RADTODEG; - - if (angle.Y < 0.0f) angle.Y += 360.0f; - if (angle.Y >= 360.0f) angle.Y -= 360.0f; - - ik_f32 z1 = (T)sqrt(X*X + Z*Z); - - angle.X = (T)atan2(z1, Y); - angle.X *= (ik_f32)IK_RADTODEG; - angle.X -= 90.0f; - - if (angle.X < 0.0f) angle.X += 360.0f; - if (angle.X >= 360) angle.X -= 360.0f; - - return angle; - } - - //! Fills an array of 4 values with the vector data (usually floats). - /** Useful for setting in shader constants for example. The fourth value - will always be 0. */ - void getAs4Values(T* array) - { - array[0] = X; - array[1] = Y; - array[2] = Z; - array[3] = 0; - } - - - // member variables - - T X, Y, Z; - }; - - - //! Typedef for a ik_f32 3d vector, a vector using floats for X, Y and Z - typedef vec3d vec3df; - - //! Typedef for an integer 3d vector, a vector using ints for X, Y and Z - typedef vec3d vec3di; - - template vec3d operator*(const S scalar, const vec3d& vector) { return vector*scalar; } - -} // end namespace irrklang - - -#endif - +// Copyright (C) 2002-2009 Nikolaus Gebhardt +// This file is part of the "irrKlang" library. +// For conditions of distribution and use, see copyright notice in irrKlang.h + +#ifndef __IRR_IRRKLANG_VEC_3D_H_INCLUDED__ +#define __IRR_IRRKLANG_VEC_3D_H_INCLUDED__ + +#include +#include "ik_irrKlangTypes.h" + + +namespace irrklang +{ + + //! a 3d vector template class for representing vectors and points in 3d + template + class vec3d + { + public: + + vec3d(): X(0), Y(0), Z(0) {}; + vec3d(T nx, T ny, T nz) : X(nx), Y(ny), Z(nz) {}; + vec3d(const vec3d& other) :X(other.X), Y(other.Y), Z(other.Z) {}; + + //! constructor creating an irrklang vec3d from an irrlicht vector. + #ifdef __IRR_POINT_3D_H_INCLUDED__ + template + vec3d(const B& other) :X(other.X), Y(other.Y), Z(other.Z) {}; + #endif // __IRR_POINT_3D_H_INCLUDED__ + + // operators + + vec3d operator-() const { return vec3d(-X, -Y, -Z); } + + vec3d& operator=(const vec3d& other) { X = other.X; Y = other.Y; Z = other.Z; return *this; } + + vec3d operator+(const vec3d& other) const { return vec3d(X + other.X, Y + other.Y, Z + other.Z); } + vec3d& operator+=(const vec3d& other) { X+=other.X; Y+=other.Y; Z+=other.Z; return *this; } + + vec3d operator-(const vec3d& other) const { return vec3d(X - other.X, Y - other.Y, Z - other.Z); } + vec3d& operator-=(const vec3d& other) { X-=other.X; Y-=other.Y; Z-=other.Z; return *this; } + + vec3d operator*(const vec3d& other) const { return vec3d(X * other.X, Y * other.Y, Z * other.Z); } + vec3d& operator*=(const vec3d& other) { X*=other.X; Y*=other.Y; Z*=other.Z; return *this; } + vec3d operator*(const T v) const { return vec3d(X * v, Y * v, Z * v); } + vec3d& operator*=(const T v) { X*=v; Y*=v; Z*=v; return *this; } + + vec3d operator/(const vec3d& other) const { return vec3d(X / other.X, Y / other.Y, Z / other.Z); } + vec3d& operator/=(const vec3d& other) { X/=other.X; Y/=other.Y; Z/=other.Z; return *this; } + vec3d operator/(const T v) const { T i=(T)1.0/v; return vec3d(X * i, Y * i, Z * i); } + vec3d& operator/=(const T v) { T i=(T)1.0/v; X*=i; Y*=i; Z*=i; return *this; } + + bool operator<=(const vec3d&other) const { return X<=other.X && Y<=other.Y && Z<=other.Z;}; + bool operator>=(const vec3d&other) const { return X>=other.X && Y>=other.Y && Z>=other.Z;}; + + bool operator==(const vec3d& other) const { return other.X==X && other.Y==Y && other.Z==Z; } + bool operator!=(const vec3d& other) const { return other.X!=X || other.Y!=Y || other.Z!=Z; } + + // functions + + //! returns if this vector equalsfloat the other one, taking floating point rounding errors into account + bool equals(const vec3d& other) + { + return equalsfloat(X, other.X) && + equalsfloat(Y, other.Y) && + equalsfloat(Z, other.Z); + } + + void set(const T nx, const T ny, const T nz) {X=nx; Y=ny; Z=nz; } + void set(const vec3d& p) { X=p.X; Y=p.Y; Z=p.Z;} + + //! Returns length of the vector. + ik_f64 getLength() const { return sqrt(X*X + Y*Y + Z*Z); } + + //! Returns squared length of the vector. + /** This is useful because it is much faster then + getLength(). */ + ik_f64 getLengthSQ() const { return X*X + Y*Y + Z*Z; } + + //! Returns the dot product with another vector. + T dotProduct(const vec3d& other) const + { + return X*other.X + Y*other.Y + Z*other.Z; + } + + //! Returns distance from an other point. + /** Here, the vector is interpreted as point in 3 dimensional space. */ + ik_f64 getDistanceFrom(const vec3d& other) const + { + ik_f64 vx = X - other.X; ik_f64 vy = Y - other.Y; ik_f64 vz = Z - other.Z; + return sqrt(vx*vx + vy*vy + vz*vz); + } + + //! Returns squared distance from an other point. + /** Here, the vector is interpreted as point in 3 dimensional space. */ + ik_f32 getDistanceFromSQ(const vec3d& other) const + { + ik_f32 vx = X - other.X; ik_f32 vy = Y - other.Y; ik_f32 vz = Z - other.Z; + return (vx*vx + vy*vy + vz*vz); + } + + //! Calculates the cross product with another vector + vec3d crossProduct(const vec3d& p) const + { + return vec3d(Y * p.Z - Z * p.Y, Z * p.X - X * p.Z, X * p.Y - Y * p.X); + } + + //! Returns if this vector interpreted as a point is on a line between two other points. + /** It is assumed that the point is on the line. */ + bool isBetweenPoints(const vec3d& begin, const vec3d& end) const + { + ik_f32 f = (ik_f32)(end - begin).getLengthSQ(); + return (ik_f32)getDistanceFromSQ(begin) < f && + (ik_f32)getDistanceFromSQ(end) < f; + } + + //! Normalizes the vector. + vec3d& normalize() + { + T l = (T)getLength(); + if (l == 0) + return *this; + + l = (T)1.0 / l; + X *= l; + Y *= l; + Z *= l; + return *this; + } + + //! Sets the lenght of the vector to a new value + void setLength(T newlength) + { + normalize(); + *this *= newlength; + } + + //! Inverts the vector. + void invert() + { + X *= -1.0f; + Y *= -1.0f; + Z *= -1.0f; + } + + //! Rotates the vector by a specified number of degrees around the Y + //! axis and the specified center. + //! \param degrees: Number of degrees to rotate around the Y axis. + //! \param center: The center of the rotation. + void rotateXZBy(ik_f64 degrees, const vec3d& center) + { + degrees *= IK_DEGTORAD64; + T cs = (T)cos(degrees); + T sn = (T)sin(degrees); + X -= center.X; + Z -= center.Z; + set(X*cs - Z*sn, Y, X*sn + Z*cs); + X += center.X; + Z += center.Z; + } + + //! Rotates the vector by a specified number of degrees around the Z + //! axis and the specified center. + //! \param degrees: Number of degrees to rotate around the Z axis. + //! \param center: The center of the rotation. + void rotateXYBy(ik_f64 degrees, const vec3d& center) + { + degrees *= IK_DEGTORAD64; + T cs = (T)cos(degrees); + T sn = (T)sin(degrees); + X -= center.X; + Y -= center.Y; + set(X*cs - Y*sn, X*sn + Y*cs, Z); + X += center.X; + Y += center.Y; + } + + //! Rotates the vector by a specified number of degrees around the X + //! axis and the specified center. + //! \param degrees: Number of degrees to rotate around the X axis. + //! \param center: The center of the rotation. + void rotateYZBy(ik_f64 degrees, const vec3d& center) + { + degrees *= IK_DEGTORAD64; + T cs = (T)cos(degrees); + T sn = (T)sin(degrees); + Z -= center.Z; + Y -= center.Y; + set(X, Y*cs - Z*sn, Y*sn + Z*cs); + Z += center.Z; + Y += center.Y; + } + + //! Returns interpolated vector. + /** \param other: other vector to interpolate between + \param d: value between 0.0f and 1.0f. */ + vec3d getInterpolated(const vec3d& other, ik_f32 d) const + { + ik_f32 inv = 1.0f - d; + return vec3d(other.X*inv + X*d, + other.Y*inv + Y*d, + other.Z*inv + Z*d); + } + + //! Gets the Y and Z rotations of a vector. + /** Thanks to Arras on the Irrlicht forums to add this method. + \return A vector representing the rotation in degrees of + this vector. The Z component of the vector will always be 0. */ + vec3d getHorizontalAngle() + { + vec3d angle; + + angle.Y = (T)atan2(X, Z); + angle.Y *= (ik_f32)IK_RADTODEG; + + if (angle.Y < 0.0f) angle.Y += 360.0f; + if (angle.Y >= 360.0f) angle.Y -= 360.0f; + + ik_f32 z1 = (T)sqrt(X*X + Z*Z); + + angle.X = (T)atan2(z1, Y); + angle.X *= (ik_f32)IK_RADTODEG; + angle.X -= 90.0f; + + if (angle.X < 0.0f) angle.X += 360.0f; + if (angle.X >= 360) angle.X -= 360.0f; + + return angle; + } + + //! Fills an array of 4 values with the vector data (usually floats). + /** Useful for setting in shader constants for example. The fourth value + will always be 0. */ + void getAs4Values(T* array) + { + array[0] = X; + array[1] = Y; + array[2] = Z; + array[3] = 0; + } + + + // member variables + + T X, Y, Z; + }; + + + //! Typedef for a ik_f32 3d vector, a vector using floats for X, Y and Z + typedef vec3d vec3df; + + //! Typedef for an integer 3d vector, a vector using ints for X, Y and Z + typedef vec3d vec3di; + + template vec3d operator*(const S scalar, const vec3d& vector) { return vector*scalar; } + +} // end namespace irrklang + + +#endif + diff --git a/src/dep/include/irrklang/irrKlang.h b/src/dep/include/irrklang/irrKlang.h index 7784f88..d81a378 100644 --- a/src/dep/include/irrklang/irrKlang.h +++ b/src/dep/include/irrklang/irrKlang.h @@ -1,966 +1,995 @@ -/* irrKlang.h -- interface of the 'irrKlang' library - - Copyright (C) 2002-2007 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" - -//! irrKlang Version -#define IRR_KLANG_VERSION "1.1.0" - -/*! \mainpage irrKlang 1.1.0 API documentation - * - *
- - * \section contents Contents - * General:
- * @ref intro
- * @ref features
- * @ref links
- *
- * 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
- *
- * 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)
    • - *
  • Amiga Modules (*.mod)
    • - *
  • Impulse Tracker (*.it)
    • - *
  • Scream Tracker 3 (*.s3d)
    • - *
  • Fast Tracker 2 (*.xm)
    • - *
- * It is also able to run on different operating systems and use several output drivers: - *
    - *
  • Windows 98, ME, NT 4, 2000, XP, Vista
    • - *
      - *
    • 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 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 - * - * // ... - * - * // 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. - *
- *
- *
- *
- * - * - * - * \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 - * \endcode - * - * Of course, IRRKLANG_STATIC can also simply be defined in the project/compiler settings instead of - * in the source file. - *
- *
- *
- *
- * - * - * - * \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; igetDeviceCount(); ++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.
- * 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; igetDeviceCount(); ++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 - * - *
- *
- *
- *
- * - * - * - * - * \section quickstartexample Quick Start Example - * - * To simply start the engine and play a mp3 file, use code like this: - * - * \code - * #include - * #include - * #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 namespaces, 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. - *
- *
- *
- *
- * - * - * - * \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 - * #include - * 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); - - -} // end namespace irrklang - - -/*! \file irrKlang.h - \brief Main header file of the irrKlang sound library, the only file needed to include. -*/ - -#endif - +/* irrKlang.h -- interface of the 'irrKlang' library + + Copyright (C) 2002-2009 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.3.0" + +/*! \mainpage irrKlang 1.3.0 API documentation + * + *
+ + * \section contents Contents + * General:
+ * @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
+ *
+ * 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)
    • + *
+ * It is also able to run on different operating systems and use several output drivers: + *
    + *
  • Windows 98, ME, NT 4, 2000, XP, Vista, Windows 7
    • + *
      + *
    • 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 + * + * // ... + * + * // 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. + *
+ *
+ *
+ *
+ * + * + * + * \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 + * \endcode + * + * Of course, IRRKLANG_STATIC can also simply be defined in the project/compiler settings instead of + * in the source file. + *
+ *
+ *
+ *
+ * + * + * + * \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; igetDeviceCount(); ++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.
+ * 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; igetDeviceCount(); ++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 + * + *
+ *
+ *
+ *
+ * + * + * + * + * \section quickstartexample Quick Start Example + * + * To simply start the engine and play a mp3 file, use code like this: + * + * \code + * #include + * #include + * #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 namespaces, 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. + *
+ *
+ *
+ *
+ * + * + * + * \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 + * #include + * 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); + + +} // end namespace irrklang + + +/*! \file irrKlang.h + \brief Main header file of the irrKlang sound library, the only file needed to include. +*/ + +#endif +