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

Returns:
  Returns true if successful, and false if not. If 'false' is returned, maybe your buffer was too small.

template<class S , class T >

vec3d<T> irrklang::operator* | ( | const S | scalar,
|  | const vec3d< T > & | vector |
| ) |  |  | `[inline]`

## Variable Documentation

const ik_f32 irrklang::IK_DEGTORAD = IK_PI32 / 180.0f

const ik_f64 irrklang::IK_DEGTORAD64 = IK_PI64 / 180.0

const ik_f32 irrklang::IK_PI32 = 3.14159265359f

const ik_f64 irrklang::IK_PI64 = 3.1415926535897932384626433832795028841971693993751

const ik_f32 irrklang::IK_RADTODEG = 180.0f / IK_PI32

const ik_f64 irrklang::IK_RADTODEG64 = 180.0 / IK_PI64

const ik_f32 irrklang::IK_ROUNDING_ERROR_32 = 0.000001f

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines

| The irrKlang Engine Documentation © 2003-2018 by Nikolaus Gebhardt. Generated by Doxygen (1.6.1)