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

If you set any SoundPoint "bump" field to UPDATE_DISABLED then it will no longer be updated and can be directly modified. For example, setting VolumeBump = UPDATE_DISABLED will stop Volume field from updating.

## Functions Summary

DopplerFrameSkip | Stops doppler effect for all objects for 1 update.
EntityPause3DSound | Pauses all entity sounds.
EntityResume3DSound | Resumes all paused entity sounds.
EntityStop3DSound | Stops all entity sounds.
Init3DSound | Set up 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 paused 3D sound.
Start3DSound | Attaches a sound to an entity and starts it playing.
Stop3DSound | Stops a single 3D sound.
Update3DSounds | Updates all the 3D sound channels.

## Types Summary

SoundPoint | SoundPoint.

## 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 affect the doppler effect then call this before your next call to Update3DSounds. For example, if you have a camera looking at an object from a distance and then "change view" by moving the camera close and behind the object. This would normally be a very fast move and cause a large doppler effect.

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

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

Function EntityStop3DSound(NoisyEntity:TEntity)
Description | Stops all entity sounds.
Information | Stops all sounds attached to an entity through the internal 3D SoundPoint list. 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.

Function Init3DSound(ListeningEntity:TEntity, MaxRange:Float, ExaggerateDopplerScale:Float=DOPPLER_DISABLED)
Description | Set up 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 amount to exaggerate the doppler effect by. Setting it to DOPPLER_DISABLED or leaving it blank will disable the doppler effect. A value of 1 will use an accurate doppler effect (1 unit = 1 meter). An appropriate value will be dependent on the speed of objects in your program.

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

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

Function Que3DSound:SoundPoint(TheSound:TSound, NoisyEntity:TEntity, Loudness:Float=1, Volume:Float=1)
Returns | SoundPoint 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 paused 3D sound.
Information | Wrapper for SoundPoint.Pause = False for more logical programming.

Function Start3DSound:SoundPoint(TheSound:TSound, NoisyEntity:TEntity, Loudness:Float=1, Volume:Float=1)
Returns | SoundPoint 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 single 3D sound.
Information | Wrapper for SoundPoint.Stop for more logical programming.

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

## Types

Type SoundPoint
Description | SoundPoint.
Information | 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 positional information and clears the channel if the sound is done playing.

Functions Summary
Create | Creates a new sound point.

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

Field DepthBump:Float
Description | Depth bump.
Information | When calculating the sound channels depth this number will be added to the new pan.

Field EmiterObject:TEntity
Description | Entity emitting the sound.

Field Loudness:Float
Description | Loudness factor of the sound.

Field MasterVolume:Float
Description | Base volume of the sound.

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

Field PanBump:Float
Description | Pan bump.
Information | When calculating the sound channels pan, this number will be added to the new pan.

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 | Play rate of the sound.

Field RateBump:Float
Description | Play rate bump.
Information | When calculating the sound channels play rate this number will be added to the new rate.

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

Field Volume:Float
Description | Volume of the sound.

Field VolumeBump:Float
Description | Volume bump.
Information | When calculating the sound channels volume this number will be added to the new volume.

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 positional information and clears 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, this allows for future changes to the system.

## Module Information

Version | 1.3
License | zlib
Copyright | 2016-2017 Mark Mcvittie
Authors | Logan Chittenden, Mark Mcvittie
History | 1.3 Release
History | Init3DSound HearingPoint fix, updated documentation
History | 1.2 Release
History | Added Stop3DSound, EntityStop3DSound, Pause3DSound, EntityPause3DSound,
History | Resume3DSound, EntityResume3DSound, fixed some memory bugs, removed redundant lines,
History | minor speed optimizations, internal restructuring, updated documentation
History | 1.1 Release
History | Added DopplerFrameSkip, Que3DSound, UPDATE_DISABLED option, List3DSounds,
History | SoundPoint playing, fixed unnecessarily confusing dopper effect
History | 1.0 Initial Release