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

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:

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

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.

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.