# Wrapper Library for IrrKlang

# Reference Manual

## Table of Contents

- Overview
- System
- Sounds

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