engine.sound Functions
Controls the general sound settings.
Sound Class
Members
void engine.sound.setAdaptation(float adaptation)
Sets sound occlusion with specified adaptation time.Arguments
- float adaptation - Time for sound adaptation to a filter, used when the sound source becomes occluded or other way round.
float engine.sound.getAdaptation()
Returns the current time set for sound adaptation, that is used when the sound source becomes occluded or other way round.Return value
Time for sound adaptation to a filter.void engine.sound.setAttenuation(int attenuation)
Sets specified sound attenuation model. Attenuation is the ability of a sound to lower in volume as the player moves away from it.Arguments
- int attenuation - One of the ATTENUATION_* variables. The default value is ATTENUATION_LINEAR_CLAMPED.
int engine.sound.getAttenuation()
Returns current sound attenuation mode.Return value
One of the ATTENUATION_* variables.void engine.sound.setData(string data)
Returns user data associated with the sound. This string is written directly into a *.world file. Namely, into the data child tag of the sound tag, for example:Source code (XML)
<world version="1.21">
<sound>
<data>User data</data>
</sound>
</world>Arguments
- string data - User data. Data can contain an XML formatted string.
string engine.sound.getData()
Returns user data associated with the sound. This string is written directly into a *.world file. Namely, into the data child tag of the sound tag, for example:Source code (XML)
<world version="1.21">
<sound>
<data>User data</data>
</sound>
</world>Return value
User data. Data can contain an XML formatted string.void engine.sound.setDoppler(float doppler)
Set the Doppler effect.Arguments
- float doppler - The Doppler factor.
float engine.sound.getDoppler()
Returns the current Doppler factor.Return value
Doppler factor.void engine.sound.setEnabled(int enabled)
Enables or disables the sound.Arguments
- int enabled - Positive integer to enable the sound; otherwise, 0.
int engine.sound.isEnabled()
Returns a value indicating if the sound is enabled.Return value
1 if the sound is enabled; otherwise, 0.void engine.sound.setHRTF(int enable)
Enables or disables HRTF modeArguments
- int enable - 1 to enable binaural sound; 0 to disable it.
int engine.sound.isHRTF()
Returns a value indicating if the binaural HRTF sound is enabled.Return value
1 if the binaural HRTF sound is enabled; otherwise, 0.void engine.sound.setScale(float scale)
Set the time scale for the sound playing.Arguments
- float scale - Sound time scale. The provided value is saturated in the range [0; 2].
float engine.sound.getScale()
Returns the current time scale for the sound playing.Return value
Sound time scale.void engine.sound.setSourceLimit(int source, int limit)
Limits the number of simultaneously played sound sources per one sound channel.Arguments
- int source - ID number of the sound channel (from 0 to 31).
- int limit - The maximum number of sound sources that can be played simultaneously.
int engine.sound.getSourceLimit(int source)
Returns the current number of simultaneously played sound sources per one sound channel.Arguments
- int source - ID number of the sound channel (from 0 to 31).
Return value
The maximum number of sound sources that can be played simultaneously.void engine.sound.setSourceVolume(int source, float volume)
Sets the volume for the specified sound channel.Arguments
- int source - ID number of the sound channel (from 0 to 31).
- float volume - Channel volume. The provided value is saturated within [0;1] range, where 0 means muted sound and 1 is the maximum volume.
float engine.sound.getSourceVolume(int source)
Returns the current volume of the specified sound channel.Arguments
- int source - ID number of the sound channel (from 0 to 31).
Return value
Channel volume.float engine.sound.getTotalTime()
Returns the total time of the sound playing.Return value
The total time value, milliseconds.void engine.sound.setVelocity(float velocity)
Sets the sound velocity.Arguments
- float velocity - Sound velocity.
float engine.sound.getVelocity()
Returns the current sound velocity.Return value
Sound velocity.void engine.sound.setVolume(float volume)
Sets the sound volume.Arguments
- float volume - Volume. 0 means muted, 1 means maximum volume.
float engine.sound.getVolume()
Returns the current sound volume.Return value
Volume. 0 means muted, 1 means maximum volume.int engine.sound.loadSettings(string name)
Load sound settings from the file with specified name.Arguments
- string name - Sound settings file name.
Return value
1 if the sound settings are loaded successfully; otherwise, 0.int engine.sound.loadWorld(Xml xml)
Loads a sound state from the Xml. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.Arguments
- Xml xml - Xml node.
Return value
1 if the sound state is loaded successfully; otherwise, 0.void engine.sound.renderWorld(int force)
Forces update of the sound system: all sound settings will be applied at once (such as play, stop events and change of parameters). A sound system has its own fixed frame rate (30 fps), while a script update rate can be much higher, which sometimes cause commands being skipped, unless a forced update is used.Arguments
- int force - 1 to force update of the sound system; otherwise, 0.
int engine.sound.restoreState(Stream stream)
Restores a sound state from the stream. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.Warning
This function is deprecated and will be removed in the next release.
Arguments
- Stream stream - Stream to restore the state from.
Return value
1 if the sound state is restored successfully; otherwise, 0.int engine.sound.saveSettings(string name, int force = 0)
Saves sound settings to the file with specified name.Arguments
- string name - Sound settings file name.
- int force - Forced saving of sound settings.
Return value
1 if the sound settings are saved successfully; otherwise, 0.int engine.sound.saveState(Stream stream)
Saves a sound state into the stream. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.Warning
This function is deprecated and will be removed in the next release.
Arguments
- Stream stream - Stream to save the state into.
Return value
1 if the sound state is saved successfully; otherwise, 0.int engine.sound.saveWorld(Xml xml, int force = 0)
Saves a sound state into the given Xml node. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.Arguments
- Xml xml - Xml node.
- int force - Forced saving of the sound state.
Return value
1 if the sound state is saved successfully; otherwise, 0.int SOUND_ATTENUATION_EXPONENT
Description
Exponential distance rolloff model, modeling an exponential dropoff in gain as distance increases between the source and listener.int SOUND_ATTENUATION_EXPONENT_CLAMPED
Description
Exponential Distance clamped model.int SOUND_ATTENUATION_INVERSE
Description
Inverse distance rolloff model.int SOUND_ATTENUATION_INVERSE_CLAMPED
Description
Inverse distance clamped model.int SOUND_ATTENUATION_LINEAR
Description
Linear distance rolloff model.int SOUND_ATTENUATION_LINEAR_CLAMPED
Description
Linear distance clamped model.int SOUND_NUM_SOURCES
Description
Number of sound sources.int SOUND_REVERB_DISABLED
Description
Reverberation is disabled.int SOUND_REVERB_MULTIPLE
Description
Multiple-environment reverberation.int SOUND_REVERB_SINGLE
Description
Single-environment reverberation.Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)