Getting Started
Migrating to UNIGINE 2.0
C++ API Migration
UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins

engine.sound Functions

This set of functions controls the general sound settings.

int SOUND_NUM_SOURCES

Description

The number of sound channels (it is equal to 32).

int SOUND_REVERB_DISABLED

Description

Reverberation of sound is disabled.

int SOUND_REVERB_MULTIPLE

Description

Sound sources reverberate between each other. That is, the sound from a sound source can reverberate inside one reverberation zone and then reverberate together with its early reflections, reverberation and echo in another reverberation zone before it reaches the player.

int SOUND_REVERB_SINGLE

Description

Reverberation is calculated only when both the player is inside the reverberation zone. Sounds sources do not reverberate between reverberation zones even when the sound passes through a number of them. Instead, all reverb parameters are interpolated and then applied as, as if there is only one reverberation zone around the player.

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.

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.

float engine.sound.getDoppler ()

Returns the current Doppler factor.

Return value

Doppler factor.

float engine.sound.getScale ()

Returns the current time scale for the sound playing.

Return value

Sound time scale.

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.

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.

float engine.sound.getVelocity ()

Returns the current sound velocity.

Return value

Sound velocity.

float engine.sound.getVolume ()

Returns the current sound volume.

Return value

Volume. 0 means muted, 1 means maximum volume.

int engine.sound.isEnabled ()

Returns a value indicating if the sound is enabled.

Return value

1 if the sound is enabled; otherwise, 0.

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

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.

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.

void engine.sound.setDoppler (float doppler)

Set the Doppler effect.

Arguments

  • float doppler - The Doppler factor.

void engine.sound.setEnabled (int enable)

Enables or disables the sound.

Arguments

  • int enable - Positive integer to enable the sound; 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].

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.

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.

void engine.sound.setVelocity (float velocity)

Sets the sound velocity.

Arguments

  • float velocity - Sound velocity.

void engine.sound.setVolume (float volume)

Sets the sound volume.

Arguments

  • float volume - Volume. 0 means muted, 1 means maximum volume.
Last update: 2017-07-03