3D Sound reference

| Openb3d.B3dsound: | Functions | Types | Modinfo | Source |

# 3D Sound

You must stop all sounds associated with an entity before freeing it. Call EntityStop3DSound() before freeing an entity if there is a chance it could be playing a sound. Failure to stop sounds associated with a non-existent entity can cause your program to crash.

## Functions Summary

DopplerFrameSkip | Stops doppler effect for all objects for 1 update.
EntityPause3DSound | Pauses all sounds attached to an entity.
EntityResume3DSound | Resumes all paused sounds attached to an entity.
EntityStop3DSound | Stops all sounds attached to an entity.
Init3DSound | Setup the 3D sound system.
List3DSounds | Finds sounds associated with an entity.
Pause3DSound | Pauses a 3D Sound.
Que3DSound | Attaches a sound to an entity but does NOT start it playing.
Resume3DSound | Resumes a pause 3D Sound.
Start3DSound | Attaches a sound to an entity and starts it playing.
Stop3DSound | Stops a 3D Sound.
Update3DSounds | Updates all the 3D sound channels.

## Types Summary

SoundPoint | SoundPoint Type.

## Functions

Function DopplerFrameSkip()
Description | Stops doppler effect for all objects for 1 update.
Information | If you need to move your listen point in a way that you do not want to have effect the doppler effect then call this before your next call to Update3DSounds. An example would be if you have a camera looking at an object from a distance and then "change view" in your game by moving the camera close and behind the object. This would normaly be a very fast move and cause a large doppler effect. Call DopplerFrameSkip() somewhere durring the camera re-position, before the next call to Update3DSounds().

Function EntityPause3DSound(NoisyEntity:TEntity)
Description | Pauses all sounds attached to an entity.
Information | Pauses all sounds that are attached to an entity through the internal 3D sound point list.

Function EntityResume3DSound(NoisyEntity:TEntity)
Description | Resumes all paused sounds attached to an entity.
Information | Resumes all paused sounds that are attached to an entity through the internal 3D sound point list.

Function EntityStop3DSound(NoisyEntity:TEntity)
Description | Stops all sounds attached to an entity.
Information | Stops all sounds that are attached to an entity through the internal 3D sound point list.

Function Init3DSound(ListeningEntity:TEntity, MaxRange:Float, ExaggerateDopplerScale:Float=DOPPLER_DISABLED)
Description | Setup the 3D sound system.

Information

Call this before any other 3D sound calls
The sound system can be re-initialized later without loosing the sounds currently playing.
ListeningEntity is the entity you will hear sound through.
MaxRange is the maximum distance a sound will be before it is silent
ExaggerateDopplerScale optional is the amound to exagerate the doppler effect bye. Setting it to DOPPLER_DISABLED, or leaving it blank will dissable the doppler effect. A value of 1 will use accurate doppler effect (1 unit = 1 meter). An appropriate value will be dependent on the speeds of objects in your program.

Function List3DSounds:TList(NoisyEntity:TEntity)
Returns | TList of Sound Points attached to the entity.
Description | Finds sounds associated with an entity.
Information | Finds and returns all sound points attached to the passed entity.

Function Pause3DSound(TheSoundPoint:SoundPoint)
Description | Pauses a 3D Sound.
Information | Wrapper for SoundPoint.Pause = True for more logical programing.

Function Que3DSound:SoundPoint(TheSound:TSound, NoisyEntity:TEntity, Loudness:Float=1, Volume:Float=1)
Returns | Sound Point so you can control the sound further. You can ignore the value as it is held in.
Description | Attaches a sound to an entity but does NOT start it playing.

Function Resume3DSound(TheSoundPoint:SoundPoint)
Description | Resumes a pause 3D Sound.
Information | Wrapper for SoundPoint.Pause = False for more logical programing.

Function Start3DSound:SoundPoint(TheSound:TSound, NoisyEntity:TEntity, Loudness:Float=1, Volume:Float=1)
Returns | Sound Point so you can control it further. You can ignore the return value as it is held in.
Description | Attaches a sound to an entity and starts it playing.

Function Stop3DSound(TheSoundPoint:SoundPoint)
Description | Stops a 3D Sound.
Information | Wrapper for SoundPoint.Stop() for more logical programing.

Function Update3DSounds()
Description | Updates all the 3D sound channels.
Information | Should be called (optimaly) once per loop, preferably after positions and collisions have been handled.

## Types

Type SoundPoint
Description | SoundPoint Type.
Information | A SoundPoint is a point that plays a sound in 3D space.

Fields Summary
Depth , DepthBump , EmiterObject , Loudness , MasterVolume , Pan , PanBump , Paused , Rate , RateBump , SoundChannel , Volume , VolumeBump

Methods Summary
Stop | Stops a sound and removes it from the sound system.
Update | Updates the sound channel and it's positional information, as well as clearing the channel if the sound is done playing.

Functions Summary
Create | Creates a new sound point.

Field Depth:Float
Description | The depth point of the sound.

Field DepthBump:Float
Description | The depth bump.
Information | When calculating the sound channels depth this number will be added to the new pan. If you set any bump vairable to UPDATE_DISABLED then that primary variable will no longer be updated and can be directly modified. For example, setting VolumeBump = UPDATE_DISABLED will stop the Volume variable from updating so you can change it Directly.

Field EmiterObject:TEntity
Description | The Entity that is emiting the sound.

Field Loudness:Float
Description | The "loudness" of the sound.

Field MasterVolume:Float
Description | The base volume of the sound.

Field Pan:Float
Description | The pan point of the sound.

Field PanBump:Float
Description | The pan bump.
Information | When calculating the sound channels pan this number will be added to the new pan. If you set any bump vairable to UPDATE_DISABLED then that primary variable will no longer be updated and can be directly modified. For example, setting VolumeBump = UPDATE_DISABLED will stop the Volume variable from updating so you can change it Directly.

Field Paused:Byte = False
Description | Pause status.
Information | If a song is paused it will still be updated and held, but will not play. To pause a sound, change it's paused value to true and update the sound.

Field Rate:Float = 1
Description | The play rate of the sound.

Field RateBump:Float
Description | The play rate bump.
Information | When calculating the sound channels play rate this number will be added to the new rate. If you set any bump vairable to UPDATE_DISABLED then that primary variable will no longer be updated and can be directly modified. For example, setting VolumeBump = UPDATE_DISABLED will stop the Volume variable from updating so you can change it Directly.

Field SoundChannel:TChannel
Description | The channel the sound is playing in.

Field Volume:Float
Description | The volume of the sound.

Field VolumeBump:Float
Description | The volume bump.
Information | When calculating the sound channels volume this number will be added to the new volume. If you set any bump vairable to UPDATE_DISABLED then that primary variable will no longer be updated and can be directly modified. For example, setting VolumeBump = UPDATE_DISABLED will stop the Volume variable from updating so you can change it Directly.

Method Stop()
Description | Stops a sound and removes it from the sound system.
Information | This will stop a sound point while playing and free it's resources.

Method Update()
Description | Updates the sound channel and it's positional information, as well as clearing the channel if the sound is done playing.
Information | To update all sounds at once use Update3DSounds()

Function Create:SoundPoint(TheSound:TSound, NoisyEntity:TEntity, EntityLoudness:Float=1, Volume:Float=1, Qued:Byte = False)
Description | Creates a new sound point.
Information | To create a sound use Start3DSound to allow for future changes to the system.

## Module Information

Version | 1.2
Author | Logan Chittenden
License | You are free to use this code as you please.
History | 1.2 Added Stop3DSound() : EntityStop3DSound() : Pause3DSound() : EntityPause3DSound() :
Resume3DSound() | EntityResume3DSound() : Fixed some misc memory bugs. Removed redundent lines.
History | 1.1 Added DopplerFrameSkip() : Que3DSound() : UPDATE_DISABLED option :
SoundPoint.Playing | List3DSounds() : Fixed un-necessarily confusing dopper effect stuff.
History | 1.0 Initial Release