Unigine::Sound Class

Header:

#include <UnigineSounds.h>

List of functions:

List of Variables:

ATTENUATION_EXPONENT
ATTENUATION_EXPONENT_CLAMPED
ATTENUATION_INVERSE
ATTENUATION_INVERSE_CLAMPED
ATTENUATION_LINEAR
ATTENUATION_LINEAR_CLAMPED
NUM_SOURCES
REVERB_DISABLED
REVERB_MULTIPLE
REVERB_SINGLE

Controls the general sound settings, such as volume, speed of sound, the Doppler factor, sound adaptation and sound mixer channels. Settings can be loaded from a *.settings file or changed by the corresponding functions below.

In the *.settings file, the sound settings are stored in the <sound> section, for example:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<settings version="2.5.0.1">
	<sound>
		<scale>1</scale>
		<volume>0.8458</volume>
		<doppler>1</doppler>
		<velocity>340.3</velocity>
		<adaptation>0.01</adaptation>
		<attenuation>3</attenuation>
		<hrtf>0</hrtf>
		<source source="0" limit="2"/>
		<source source="1" limit="4"/>
		<source source="2" limit="4"/>
		<source source="4" volume="0.4"/>
	</sound>
</settings>

Usage Example

The following example shows how to load sound settings from the *.settings, change them and then save back to the sound settings file.

AppWorldLogic.cpp

Source code (C++)

#include "AppWorldLogic.h"
#include <UnigineApp.h>
#include <UnigineGame.h>
#include <UnigineLog.h>
#include <UnigineProfiler.h>
#include <UnigineSounds.h>

using namespace Unigine;

AmbientSourcePtr source;

int AppWorldLogic::init() {

	// load sound settings from a file
	Sound::get()->loadSettings("unigine_project/sound_settings.settings");

	// create a sound source that plays a sample
	source = AmbientSource::create("unigine_project/sounds/ambient_source.oga",1);
	source->setLoop(1);
	source->play();

	return 1;
}

int AppWorldLogic::update() {

	// enable/disable sounds in the scene
	if (App::get()->clearKeyState('z')) {
		Sound::get()->setEnabled(!Sound::get()->isEnabled());
		Log::message("The enabled flag is %d\n", Sound::get()->isEnabled());
	}

	// print the current speed of sound
	if (App::get()->clearKeyState('c')) {
		Log::message("Sound velocity: %f\n",Sound::get()->getVelocity());
	}

	// make the sound louder
	if (App::get()->clearKeyState('n')) {
		if (Sound::get()->getVolume() != 1.0f) Sound::get()->setVolume(Sound::get()->getVolume() + 0.1f);
		Log::message("The sound is louder %f\n", Sound::get()->getVolume());
	}

	// make the sound quieter
	if (App::get()->getKeyState('m')) {
		if (Sound::get()->getVolume() > 0.0f) Sound::get()->setVolume(Sound::get()->getVolume() - 0.1f);
		Log::message("The sound is quieter %f\n", Sound::get()->getVolume());
	}

	return 1;
}

int AppWorldLogic::shutdown() {
	
	// save the sound settings into the file
	Sound::get()->saveSettings("unigine_project/sound_settings.settings",1);

	return 1;
}

Sound Class

Members

Sound * get()

Returns a pointer to the existing Sound instance.

Source code (C++)

Sound::get()->getData();

Return value

A pointer to the Sound instance.

void setAdaptation(float adaptation)

Sets sound occlusion with the 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 the specified sound attenuation mode. 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 the current sound attenuation mode.

Return value

One of the ATTENUATION_* variables.

void setData(const char * data)

Sets user data associated with the world. This string is written directly into a *.world file, 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

const char * data - New user data. Data can contain an XML formatted string

const char * getData()

Returns user string data associated with the world. This string is written directly into the data tag of the *.world file, 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 setDoppler(float doppler)

Sets the Doppler factor. By default, it is set to 1.0f.

Arguments

float doppler - Doppler factor.

float getDoppler()

Returns the current Doppler factor. The default value is 1.0f.

Return value

Doppler factor.

void setEnabled(int enabled)

Enables or disables all sounds in the scene.

Arguments

int enabled - 1 to enable all sounds, 0 to disable them.

int isEnabled()

Returns a value indicating if sounds in the scene are enabled.

Return value

1 if sounds are enabled; otherwise, 0.

void setHRTF(int hrtf)

Enables or disables the HRTF (Head Related Transfer Function) mode. This mode provides imitation of the surround sound for the stereo wired headset.

Arguments

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

int isHRTF()

Returns a value indicating if the binaural HRTF (Head Related Transfer Function) sound is enabled. An HRTF provides imitation of the surround sound for the stereo wired headset.

Return value

1 if the binaural 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 clamped in the range [0; 2].

float getScale()

Returns the current time scale for the sound playing.

Return value

Sound time scale.

void setSourceLimit(int mixer, int limit)

Limits the number of simultaneously played sound sources per one mixer channel.

Arguments

int mixer - Number of the mixer channel (from 0 to 31).
int limit - The maximum number of sound sources that can be played simultaneously.

int getSourceLimit(int mixer)

Returns the current number of simultaneously played sound sources per one mixer channel.

Arguments

int mixer - Number of the mixer channel (from 0 to 31).

Return value

The maximum number of sound sources that can be played simultaneously.

void setSourceVolume(int mixer, float volume)

Sets the volume of the specified mixer channel.

Arguments

int mixer - Number of the mixer channel (from 0 to 31).
float volume - Channel volume. The provided value is clamped 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 mixer channel.

Arguments

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

Return value

Volume of the specified mixer 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 asynchronous loading sounds.

Return value

The total time value, milliseconds.

void setVelocity(float velocity)

Sets the sound velocity (the speed of sound). By default, it is set to 343.3f.

Arguments

float velocity - Sound velocity.

float getVelocity()

Returns the current sound velocity (the speed of sound). The default velocity is 343.3f.

Return value

Sound velocity.

void setVolume(float volume)

Sets the sound volume. By default, it is set to 1.0f.

Arguments

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

float getVolume()

Returns the current sound volume. The default value is 1.0f.

Return value

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

int loadSettings(const char * name)

Loads the sound settings from the given file.

Arguments

const char * name - Path to a sound settings file (*.settings).

Return value

1 if the sound 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

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

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). For example, if you have a sound sample playing and you want to update the time, from which the sample should be played, you can perform as follows:

Source code (C++)

AmbientSourcePtr sound = AmbientSource::create("unigine_project/ambient_sample.oga");
// ...
// check if the sound sample is playing
if (sound->isPlaying())
{
	// stop playing the sample
	sound->stop();
	// apply all sound settings (if they have been changed previously)
	Sound::get()->renderWorld(1);
	// update time
	sound->setTime(45.0f);
	// countinue playing the sample 
	sound->play();
}

sound->setTime() doesn't set time immediately to the specified value: it waits for the next update to do this. So, forcing update of sound system allows for setting time immediately.

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.

Warning

This function is deprecated and will be removed in the next release.

Arguments

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

Return value

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

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

Saves the current sound settings to the given file.

Arguments

const char * name - Path to a sound settings file (*.settings).
int force - Force flag indcating if forced saving of sound settings is enabled.

Return value

1 if the sound 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.

Warning

This function is deprecated and will be removed in the next release.

Arguments

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

Return value

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

const Ptr<Xml> & xml - Xml smart pointer.
int force - Force flag indicating if forced saving of the sound state is enabled.

Return value

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.

Last update: 2017-10-20

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)