Wrapper Library for IrrKlang

Reference Manual


Table of Contents



Overview

Before using this manual I suggest that you first read the introduction document that will introduce the basic concepts. While I have made great effort to make this document both comprehensive and accurate there are bound to be errors and omissions please be careful when relying on the information when solving problems.

IrrKlang is a simple and powerful audio engine that has a wide range of operations that can be used for adding audio media to your application, it has an impressive, clean and well designed object oriented structure that is linked to through a simple DLL interface.

Unfortunately its object oriented structure makes it extremely difficult to use from imperative languages like FreeBasic that do not support an object model. This is where the wrapper come in. It provides an interface between languages like FreeBasic and the objected oriented model of IrrKlang. Many functions are translated into simple calls that return the objects back to FreeBasic as simple variables that it can then manage, there is some overhead in going through the wrapper although the interface code has been kept simple to reduce to a minimum.


System

These calls deal with starting, running and stopping the IrrKlang engine, it also includes calls that control the overall sound engine and some other miscellaneous tools.
IrrKlangStart
Syntax
IrrKlangStart

Description
Starts the IrrKlang interface ready to manage sounds.

Example
IrrKlangStart
IrrKlangStop

IrrKlangUpdate
Syntax
IrrKlangUpdate

Description
Update the IrrKlang system when running in single threaded mode. Please not that IrrKlang is now started in multi-threaded mode and this call is not needed at this time.

Example
IrrKlangStart
While NOT Inkey = "q"
    IrrKlangUpdate
Wend
IrrKlangStop

IrrKlangPlay2D
Syntax
irr_sound = IrrKlangPlay2D ( file as zstring ptr, playLooped as uinteger, startPaused as uinteger, track as uinteger, streamMode, enableSoundEffects )

Description
Play a 2D sound, this sound is unaffected by the location of the listener and is idea for music or ambient sound. To use any of the sound effect functions you need to set the track property to IRR_KLANG_TRUE.

file provides the filename and path to the sound.
playLooped determines whether the sound will repeat once it has finished. By default this is set to IRR_KLANG_FALSE
startPaused determines whether the sound starts paused. By default this is set to IRR_KLANG_FALSE
track determines whether the sound object is returned as a sound object or simply played and discarded. By default this is set to IRR_KLANG_FALSE
streamMode determines how the sound is loaded and played. By default the mode is ESM_AUTO_DETECT
    ESM_AUTO_DETECT
    ESM_STREAMING
    ESM_NO_STREAMING
    ESM_FORCE_32_BIT

enableSoundEffects enables sound effects on this sound. By default this is set to IRR_KLANG_FALSE

Example
IrrKlangPlay2D ( "./media/introduction.wav" )

IrrKlangPlay3D
Syntax
irr_sound = IrrKlangPlay3D ( file as zstring ptr, positionX, as single, positionY as single, positionZ as single, playLooped as uinteger, startPaused as uinteger, track as uinteger, streamMode, enableSoundEffects )

Description
Play a 3D sound, the volume and stereo balance of this sound is affected by the location of the listener and the location of the sound, this is ideal for a sound that is sourced from a specific location such as a person shouting or the sound of a gunshot. To use any of the sound effect functions you need to set the track property to IRR_KLANG_TRUE.

file provides the filename and path to the sound.
positionX, positionY, positionZ define the spacial co-ordinates of the sound
playLooped determines whether the sound will repeat once it has finished. By default this is set to IRR_KLANG_FALSE
startPaused determines whether the sound starts paused. By default this is set to IRR_KLANG_FALSE
track determines whether the sound object is returned as a sound object or simply played and discarded. By default this is set to IRR_KLANG_FALSE,
streamMode determines how the sound is loaded and played. By default the mode is ESM_AUTO_DETECT
    ESM_AUTO_DETECT
    ESM_STREAMING
    ESM_NO_STREAMING
    ESM_FORCE_32_BIT

enableSoundEffects enables sound effects on this sound. By default this is set to IRR_KLANG_FALSE

Example
IrrKlangPlay3D ( "./media/footsteps.wav", monsterX, monsterY, monsterZ )
IrrKlangSetAllSoundsPaused
Syntax
IrrKlangSetAllSoundsPaused ( pause as integer )

Description
Pauses all sounds effectivly muting the application.

Example
IrrKlangSetAllSoundsPaused( IRR_KLANG_TRUE )

IrrKlangStopAllSounds
Syntax
IrrKlangStopAllSounds

Description
Perminantly stop all playing sounds.

Example
IrrKlangStopAllSounds

IrrRemoveSoundSource
Syntax
IrrRemoveSoundSource(  file as zstring ptr )

Description
Removes the specified sound source from memory freeing up resources.

Example
IrrRemoveSoundSource( "./media/level_01_music.mod" )

IrrKlangRemoveAllSoundSources
Syntax
IrrKlangRemoveAllSoundSources

Description
Stop all sounds and remove all sound files from memory.

Example
IrrKlangRemoveAllSoundSources

IrrKlangSetListenerPosition
Syntax
IrrKlangSetListenerPosition ( posX as single, posY as single, posZ as single, lookX as single, lookY as single, lookZ as single, velocityX as single, velocityY as single, velocityZ as single, upX as single, upY as single, upZ as single )

Description
Set the position of the observer effecting the volume and stereo balance of 3D sounds.

posX, posY, posZ define the position of the observer in space.
lookX, lookY, lookZ define the position at which the observer is looking
velocityX, velocityY, velocityZ define the velocity of the observer (this is only required for doppler effects). By default this vector is set to 0,0,0
upX, upY, upZ define the upward direction of the observer (useful for when an observer is in a rolling vehicle for example). By default this vector is set to 0,1,0

Example
IrrKlangSetListenerPosition( HeroX,HeroY,HeroZ, TargetX,TargetY,TargetZ )

IrrKlangStop
Syntax
IrrKlangStop

Description
Stop the sound engine.

Example
IrrStop


Sounds

These calls allow you manage sounds you have loaded. These sound commands can only be used on 2D and 3D sounds that have been started with the track property set to IRR_KLANG_TRUE.

IrrReleaseSound
Syntax
IrrReleaseSound ( sound as irr_sound )

Description
Remove the sound from memory.

Example
IrrReleaseSound( BarkingSound )

IrrKlangGetPlayLength
Syntax
uinteger = IrrKlangGetPlayLength ( sound as irr_sound )

Description
Get the play length of the sound in miliseconds.

Example
DIM soundLength as uinteger = IrrKlangGetPlayLength( userSample )

IrrKlangGetPlayPosition
Syntax
uinteger = IrrKlangGetPlayPosition ( sound as irr_sound )

Description
Get the position of play in the sound in milliseconds.

Example
playPosition = IrrKlangGetPlayPosition( timeoutSound )

IrrKlangIsFinished
Syntax
uinteger = IrrKlangIsFinished ( sound as irr_sound )

Description
Read a mouse event from the Irrlicht window the properties of the mouse event are stored in the returned type.

Example
while IrrKlangIsFinished = IRR_KLANG_FALSE
    sleep 1
wend

IrrKlangSetIsPaused
Syntax
IrrKlangSetIsPaused ( sound as irr_sound, pause as uinteger )

Description
Pause and unpause the sound

Example
IrrKlangSetIsPaused ( currentTrack, IRR_KLANG_TRUE )

IrrKlangSetPlaybackSpeed
Syntax
IrrKlangSetPlaybackSpeed ( sound as irr_sound, speed as single )

Description
Set the playback speed of the sound.

Example
IrrKlangSetPlaybackSpeed ( strangeVoice, 0.5 )

IrrKlangSetPlayPosition
Syntax
IrrKlangSetPlayPosition ( sound as irr_sound, position as uinteger )

Description
Set the playback position of the sound in miliseconds.

Example
IrrKlangSetPlayPosition ( musicTrack, 5000 )

IrrKlangSetPosition
Syntax
IrrKlangSetPosition ( sound as irr_sound, positionX as single, positionY as single, positionZ as single )

Description
Set the position of the sound in 3D space.

Example
IrrKlangSetPosition ( spookyGrowl, monsterX, monsterY, monsterZ )

IrrKlangSetVolume
Syntax
IrrKlangSetVolume ( sound as irr_sound, volume as single )

Description
Set the volume of the sound.

Example
IrrKlangSetVolume ( brokenTurbine, 0.25 )

IrrKlangSetMinDistance
Syntax
IrrKlangSetMinDistance ( sound as irr_sound, distance as single )

Description
Set the minimum distance at which the sound can be heard, at this distance from the sound the volume will be zero.

Example
IrrKlangSetMinDistance ( helicopterEngine, 400.0 )

IrrKlangStopSound
Syntax
IrrKlangStopSound ( sound as irr_sound, distance as single )

Description
Stop the sound playing.

Example
IrrKlangStopSound ( fallingBoxes )