irrklang Namespace Reference

Everything in the irrKlang Sound Engine can be found in this namespace. More...

Classes
class	IAudioRecorder
	Interface to an audio recorder. Create it using the createIrrKlangAudioRecorder() function. More...
class	ICapturedAudioDataReceiver
	Interface to be implemented by the user if access to the recorded audio data is needed. More...
class	IAudioStream
	Reads and decodes audio data into an usable audio stream for the ISoundEngine. More...
class	IAudioStreamLoader
	Class which is able to create an audio file stream from a file. More...
class	IFileFactory
	Interface to overwrite file access in irrKlang. More...
class	IFileReader
	Interface providing read acess to a file. More...
class	IRefCounted
	Base class of most objects of the irrKlang. More...
class	ISound
	Represents a sound which is currently played. More...
class	ISoundDeviceList
	A list of sound devices for a sound driver. Use irrklang::createSoundDeviceList() to create this list. More...
class	ISoundEffectControl
	Interface to control the active sound effects (echo, reverb,...) of an ISound object, a playing sound. More...
class	ISoundEngine
	Interface to the sound engine, for playing 3d and 2d sound and music. More...
struct	SInternalAudioInterface
	structure for returning pointers to the internal audio interface. More...
class	ISoundMixedOutputReceiver
	Interface to be implemented by the user, which recieves the mixed output when it it played by the sound engine. More...
class	ISoundSource
	A sound source describes an input file (.ogg, .mp3, .wav or similar) and its default settings. More...
class	ISoundStopEventReceiver
	Interface to be implemented by the user, which recieves sound stop events. More...
class	IVirtualRefCounted
	Reference counting base class for objects in the Irrlicht Engine similar to IRefCounted. More...
struct	SAudioStreamFormat
	structure describing an audio stream format with helper functions More...
class	vec3d
	a 3d vector template class for representing vectors and points in 3d More...
Typedefs
typedef unsigned char	ik_u8
	8 bit unsigned variable.
typedef signed char	ik_s8
	8 bit signed variable.
typedef char	ik_c8
	8 bit character variable.
typedef unsigned short	ik_u16
	16 bit unsigned variable.
typedef signed short	ik_s16
	16 bit signed variable.
typedef unsigned int	ik_u32
	32 bit unsigned variable.
typedef signed int	ik_s32
	32 bit signed variable.
typedef float	ik_f32
	32 bit floating point variable.
typedef double	ik_f64
	64 bit floating point variable.
typedef vec3d< ik_f32 >	vec3df
	Typedef for a ik_f32 3d vector, a vector using floats for X, Y and Z.
typedef vec3d< ik_s32 >	vec3di
	Typedef for an integer 3d vector, a vector using ints for X, Y and Z.
Enumerations
enum	E_SOUND_ENGINE_OPTIONS { ESEO_MULTI_THREADED = 0x01, ESEO_MUTE_IF_NOT_FOCUSED = 0x02, ESEO_LOAD_PLUGINS = 0x04, ESEO_USE_3D_BUFFERS = 0x08, ESEO_PRINT_DEBUG_INFO_TO_DEBUGGER = 0x10, ESEO_PRINT_DEBUG_INFO_TO_STDOUT = 0x20, ESEO_LINEAR_ROLLOFF = 0x40, 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, ESEO_FORCE_32_BIT = 0x7fffffff }
	An enumeration for all options for starting up the sound engine. More...
enum	E_SOUND_OUTPUT_DRIVER { ESOD_AUTO_DETECT = 0, ESOD_DIRECT_SOUND_8, ESOD_DIRECT_SOUND, ESOD_WIN_MM, ESOD_ALSA, ESOD_CORE_AUDIO, ESOD_NULL, ESOD_COUNT, ESOD_FORCE_32_BIT = 0x7fffffff }
	An enumeration for all types of supported sound drivers. More...
enum	E_STREAM_MODE { ESM_AUTO_DETECT = 0, ESM_STREAMING, ESM_NO_STREAMING, ESM_FORCE_32_BIT = 0x7fffffff }
	An enumeration for all types of supported stream modes. More...
enum	E_STOP_EVENT_CAUSE { ESEC_SOUND_FINISHED_PLAYING = 0, ESEC_SOUND_STOPPED_BY_USER, ESEC_SOUND_STOPPED_BY_SOURCE_REMOVAL, ESEC_FORCE_32_BIT = 0x7fffffff }
	An enumeration listing all reasons for a fired sound stop event. More...
enum	ESampleFormat { ESF_U8, ESF_S16 }
	audio sample data format enumeration for supported formats More...
Functions
bool	equalsfloat (const ik_f32 a, const ik_f32 b, const ik_f32 tolerance=IK_ROUNDING_ERROR_32)
template<class S , class T >
vec3d< T >	operator* (const S scalar, const vec3d< T > &vector)
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 an irrKlang device. The irrKlang device is the root object for using the sound engine.
IRRKLANG_API ISoundDeviceList *IRRKLANGCALLCONV	createSoundDeviceList (E_SOUND_OUTPUT_DRIVER driver=ESOD_AUTO_DETECT, const char *sdk_version_do_not_use=IRR_KLANG_VERSION)
	Creates a list of available sound devices for the driver type.
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 an irrKlang audio recording device. The IAudioRecorder is the root object for recording audio.
IRRKLANG_API ISoundDeviceList *IRRKLANGCALLCONV	createAudioRecorderDeviceList (E_SOUND_OUTPUT_DRIVER driver=ESOD_AUTO_DETECT, const char *sdk_version_do_not_use=IRR_KLANG_VERSION)
	Creates a list of available recording devices for the driver type.
IRRKLANG_API bool IRRKLANGCALLCONV	makeUTF8fromUTF16string (const wchar_t pInputString, char pOutputBuffer, int outputBufferSize)
	Converts a wchar_t string to an utf8 string, useful when using Windows in unicode mode.
Variables
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

Detailed Description

Everything in the irrKlang Sound Engine can be found in this namespace.

Typedef Documentation

typedef char irrklang::ik_c8

8 bit character variable.

This is a typedef for char, it ensures portability of the engine.

typedef float irrklang::ik_f32

32 bit floating point variable.

This is a typedef for float, it ensures portability of the engine.

typedef double irrklang::ik_f64

64 bit floating point variable.

This is a typedef for double, it ensures portability of the engine.

typedef signed short irrklang::ik_s16

16 bit signed variable.

This is a typedef for signed short, it ensures portability of the engine.

typedef signed int irrklang::ik_s32

32 bit signed variable.

This is a typedef for signed int, it ensures portability of the engine.

typedef signed char irrklang::ik_s8

8 bit signed variable.

This is a typedef for signed char, it ensures portability of the engine.

typedef unsigned short irrklang::ik_u16

16 bit unsigned variable.

This is a typedef for unsigned short, it ensures portability of the engine.

typedef unsigned int irrklang::ik_u32

32 bit unsigned variable.

This is a typedef for unsigned int, it ensures portability of the engine.

typedef unsigned char irrklang::ik_u8

8 bit unsigned variable.

This is a typedef for unsigned char, it ensures portability of the engine.

typedef vec3d<ik_f32> irrklang::vec3df

Typedef for a ik_f32 3d vector, a vector using floats for X, Y and Z.

typedef vec3d<ik_s32> irrklang::vec3di

Typedef for an integer 3d vector, a vector using ints for X, Y and Z.

Enumeration Type Documentation

enum irrklang::E_SOUND_ENGINE_OPTIONS

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.

Enumerator:

ESEO_MULTI_THREADED	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_MUTE_IF_NOT_FOCUSED	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_LOAD_PLUGINS	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_USE_3D_BUFFERS	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_PRINT_DEBUG_INFO_TO_DEBUGGER	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_STDOUT	Prints debug messages to stdout (the ConsoleWindow). irrKlang will print debug info and status messages stdout, the console window in Windows.
ESEO_LINEAR_ROLLOFF	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_DEFAULT_OPTIONS	Default parameters when starting up the engine.
ESEO_FORCE_32_BIT	Never used, it only forces the compiler to compile these enumeration values to 32 bit. Don't use this.

enum irrklang::E_SOUND_OUTPUT_DRIVER

An enumeration for all types of supported sound drivers.

Values of this enumeration can be used as parameter when calling createIrrKlangDevice().

Enumerator:

ESOD_AUTO_DETECT	Autodetects the best sound driver for the system.
ESOD_DIRECT_SOUND_8	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	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_WIN_MM	WinMM sound output driver, windows only. Supports the ISoundMixedOutputReceiver interface using setMixedDataOutputReceiver.
ESOD_ALSA	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_CORE_AUDIO	Core Audio sound output driver, mac os only. Supports the ISoundMixedOutputReceiver interface using setMixedDataOutputReceiver.
ESOD_NULL	Null driver, creating no sound output.
ESOD_COUNT	Amount of built-in sound output drivers.
ESOD_FORCE_32_BIT	This enumeration literal is never used, it only forces the compiler to compile these enumeration values to 32 bit.

enum irrklang::E_STOP_EVENT_CAUSE

An enumeration listing all reasons for a fired sound stop event.

Enumerator:

ESEC_SOUND_FINISHED_PLAYING	The sound stop event was fired because the sound finished playing.
ESEC_SOUND_STOPPED_BY_USER	The sound stop event was fired because the sound was stopped by the user, calling ISound::stop().
ESEC_SOUND_STOPPED_BY_SOURCE_REMOVAL	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_FORCE_32_BIT	This enumeration literal is never used, it only forces the compiler to compile these enumeration values to 32 bit.

enum irrklang::E_STREAM_MODE

An enumeration for all types of supported stream modes.

Enumerator:

ESM_AUTO_DETECT	Autodetects the best stream mode for a specified audio data.
ESM_STREAMING	Streams the audio data when needed.
ESM_NO_STREAMING	Loads the whole audio data into the memory.
ESM_FORCE_32_BIT	This enumeration literal is never used, it only forces the compiler to compile these enumeration values to 32 bit.

enum irrklang::ESampleFormat

audio sample data format enumeration for supported formats

Enumerator:

ESF_U8	one unsigned byte (0;255)
ESF_S16	16 bit, signed (-32k;32k)

Function Documentation

IRRKLANG_API ISoundDeviceList* IRRKLANGCALLCONV irrklang::createAudioRecorderDeviceList	(	E_SOUND_OUTPUT_DRIVER	driver = `ESOD_AUTO_DETECT`,
		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.

Parameters:

	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.
	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.

Returns:: 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 IAudioRecorder* IRRKLANGCALLCONV irrklang::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 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 Recording Audio 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).

Parameters:

	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.
	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.
	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.
	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.

Returns:: 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 irrklang::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 an irrKlang device. The irrKlang device is the root object for using the sound engine.

Parameters:

	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.
	options	A combination of irrklang::E_SOUND_ENGINE_OPTIONS literals. Default value is irrklang::ESEO_DEFAULT_OPTIONS.
	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 Enumerating sound devices for an example or ISoundDeviceList or details.
	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.

Returns:: 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 ISoundDeviceList* IRRKLANGCALLCONV irrklang::createSoundDeviceList	(	E_SOUND_OUTPUT_DRIVER	driver = `ESOD_AUTO_DETECT`,
		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 Enumerating sound devices for an example on how to use this.

Parameters:

	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.
	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.

Returns:: 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.

bool irrklang::equalsfloat	(	const ik_f32	a,
		const ik_f32	b,
		const ik_f32	tolerance = `IK_ROUNDING_ERROR_32`
	)			`[inline]`

returns if a float equals the other one, taking floating point rounding errors into account

IRRKLANG_API bool IRRKLANGCALLCONV irrklang::makeUTF8fromUTF16string	(	const wchar_t *	pInputString,
		char *	pOutputBuffer,
		int	outputBufferSize
	)

Converts a wchar_t string to an utf8 string, useful when using Windows in unicode mode.

irrKlang works with unicode file names, and accepts char* strings as parameters for names and filenames. If you are running irrKlang in Windows, and working with wchar_t* pointers instead of char* ones, you can use this function to create a char* (UTF8) representation of your wchar_t* (UTF16) string. Works for filenames and other strings.

Parameters:

	pInputString	zero terminated input string.
	pOutputBuffer	the buffer where the converted string is written to. Be sure that this buffer has a big enough size. A good size would be three times the string length of your input buffer, like wcslen(yourInputBuffer)*3. Because each wchar_t can be represented by up to 3 chars.
	outputBufferSize	size of your output buffer.