Unigine::Sound Class

Controls the general sound settings.

Sound Class

Members

---

Sound * get()

Returns a pointer to the existing Sound instance.

Return value

A pointer to the Sound instance.

void 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 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 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 getAttenuation()

Returns current sound attenuation mode.

Return value

One of the ATTENUATION_* variables.

void setData(const char * data)

Sets user data associated with the world. In the *.world file, the data is set in the data tag.

Arguments

• const char * data - New user data.

const char * getData()

Returns user string data associated with the world. This string is written directly into the data tag of the *.world file.

Return value

User string data.

void setDoppler(float doppler)

Set the Doppler effect.

Arguments

• float doppler - The Doppler factor.

float getDoppler()

Returns the current Doppler factor.

Return value

Doppler factor.

void setEnabled(int enabled)

Enables or disables the sound.

Arguments

• int enabled - 1 to enable the sound, 0 to disable it.

int isEnabled()

Returns a value indicating if the sound is enabled.

Return value

1 if the sound is enabled; otherwise, 0.

void setHRTF(int hrtf)

Enables or disables HRTF mode.

Arguments

• int hrtf - 1 to enable binaural sound; 0 to disable it.

int 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 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 getScale()

Returns the current time scale for the sound playing.

Return value

Sound time scale.

void 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 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 setSourceVolume(int source, float volume)

Sets the volume of the specified sound channel.

Arguments

• int source - 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 getSourceVolume(int source)

Returns the current volume of the specified sound channel.

Arguments

• int source - Number of the sound channel (from 0 to 31).

Return value

Volume of the specified sound channel. The returning value is in range [0;1], where 0 means muted sound and 1 is the maximum volume.

float getTotalTime()

Returns the total time of the sound playing.

Return value

The total time value, milliseconds.

void setVelocity(float velocity)

Sets the sound velocity.

Arguments

• float velocity - Sound velocity.

float getVelocity()

Returns the current sound velocity.

Return value

Sound velocity.

void setVolume(float volume)

Sets the sound volume in range [0;1]. The default is 1 that means maximum volume.

Arguments

• float volume - Sound volume. 0 means muted sound, 1 means maximum volume.

float getVolume()

Returns the current sound volume.

Return value

Sound volume. 0 means muted sound, 1 means maximum volume.

int loadSettings(const char * name)

Loads the sound settings from a given file.

Arguments

• const char * name - Sound settings file name.

Return value

Returns 1 if the settings are loaded successfully; otherwise, 0.

int loadWorld(const Ptr<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

• const Ptr<Xml> & xml - Xml smart pointer.

Return value

Returns 1 if the sound state is loaded successfully; otherwise, 0 is returned.

void 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 restoreState(const Ptr<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

• const Ptr<Stream> & stream - Stream smart pointer.

Return value

Returns 1 if the sound state is restored successfully; otherwise, 0 is returned.

int saveSettings(const char * name, int force = 0)

Saves the current sound settings to a given file.

Arguments

• const char * name - Sound settings file name.
• int force - saving of sound settings.

Return value

Returns 1 if the settings are saved successfully ; otherwise, 0.

int saveState(const Ptr<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

• const Ptr<Stream> & stream - Stream smart pointer.

Return value

Returns 1 if the sound state is saved successfully; otherwise, 0.

int saveWorld(const Ptr<Xml> & xml, int force = 0)

Saves a sound state into 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

• const Ptr<Xml> & xml - Xml smart pointer.
• int force - saving of the sound state.

Return value

Returns 1 if the sound state is saved successfully; otherwise, 0.

---

int ATTENUATION_EXPONENT

Description

Exponential distance rolloff model, modeling an exponential dropoff in gain as distance increases between the source and listener.

int ATTENUATION_EXPONENT_CLAMPED

Description

Exponential Distance clamped model.

int ATTENUATION_INVERSE

Description

Inverse distance rolloff model.

int ATTENUATION_INVERSE_CLAMPED

Description

Inverse distance clamped model.

int ATTENUATION_LINEAR

Description

Linear distance rolloff model.

int ATTENUATION_LINEAR_CLAMPED

Description

Linear distance clamped model.

int NUM_SOURCES

Description

Number of sound sources.

int REVERB_DISABLED

Description

Reverberation is disabled.

int REVERB_MULTIPLE

Description

Multiple-environment reverberation.

int REVERB_SINGLE

Description

Single-environment reverberation.