Unigine::SoundSource Class

Header:	#include <UnigineSounds.h>
Inherits:	Node

This class is used to create directional sound sources. The source's sound fades out linearly in a specified range (see getMinDistance() and getMaxDistance()). If inner and outer sound cones are defined, they will also have their share in the attenuation factor (see the getConeInnerAngle() and getConeOuterAngle() functions).

NoticeAttenuation is available only for mono sound sources. If a source is the stereo one, it won't attenuate with the distance.

Sound sources are automatically handled by the sound manager. When the sound source is within the audible range, it is loaded into the memory (a full sample or its chunk, depending on whether the source is static or streamed). When it gets outside the audible range, the sound file is automatically deleted from the memory. Static sound sources are instanced; streamed ones are not.
If you still want to manage a sound source manually, you can check if it has stopped playing and after that delete it.

There is also no limitation on the number of sound sources in the world, as only currently audible ones are rendered. In the worst case scenario, when the number of simultaneously heard sound sources exceeds the hardware capabilities, some of them will not played.

Creating a Sound Source#

To create a sound source, create an instance of the SoundSource class and specify all required settings:

Source code (C++)

// create a new sound source using the given sound sample file
SoundSourcePtr sound = SoundSource::create("sound.mp3");

// disable sound muffling when being occluded
sound->setOcclusion(0);
// set the distance at which the sound gets clear
sound->setMinDistance(10.0f);
// set the distance at which the sound becomes out of audible range
sound->setMaxDistance(100.0f);
// set the gain that result in attenuation of 6 dB
sound->setGain(0.5f);
// loop the sound
sound->setLoop(1);
// start playing the sound sample 
sound->play();

Updating an Existing Sound Source#

To update the sound source settings, you can call the corresponding methods:

Source code (C++)

// change the sample file of the playing sound source
if ((sound->isPlaying()) && (App::clearKeyState('c')))
{
	// specify a new sample file
	sound->setSampleName("sound_1.mp3");
	// reduce the gain
	sound->setGain(0.2f);
}

As sound has its own thread that updates at 30 FPS, changes won't be applied immediately. However, you can force updating by using the renderWorld() method.

Sound events like play() or stop() aren't updated immediately as well. So, when you need to perform operations that require stopping of the playback (for example, updating the time, from which the sample should be played), you need to force update the sound thread after stopping the playback:

Source code (C++)

// check if the sound sample is playing
if (sound->isPlaying())
{
	// stop playing the sample
	sound->stop();
	// force updating of the sound thread
	Sound::renderWorld(1);
	// update time
	sound->setTime(0.0f);
	// play the sample 
	sound->play();
}

Methods:

Name	Description View: Sort by:
*create*	Constructor.
setAirAbsorption	Updates the air absorption value for the sound source that determines the distance-dependent attenuation of the reverberation sound at high frequencies caused by the propagation medium.
getAirAbsorption	Returns the current air absorption value for the sound source that determines the distance-dependent attenuation of the reverberation sound at high frequencies caused by the propagation medium.
setConeInnerAngle	Updates an angle of the inner sound cone.
getConeInnerAngle	Returns the current angle of the inner sound cone.
setConeOuterAngle	Updates an angle of the outer sound cone.
getConeOuterAngle	Returns the current angle of the outer sound cone.
setConeOuterGain	Updates the gain controlling the sound intensity outside the oriented cone defined by the outer angle.
getConeOuterGain	Returns the current gain controlling the sound intensity outside the oriented cone defined by the outer angle.
setConeOuterGainHF	Updates the gain filter value for the sound source that attenuates the reverberation sound at high frequencies outside the oriented cone.
getConeOuterGainHF	Returns the current gain filter value for the sound source that attenuates the reverberation sound at high frequencies outside the oriented cone.
setGain	Updates the gain controlling the sound intensity.
getGain	Returns the current gain controlling the sound intensity.
getLength	Returns the total length of the sound sample.
setLoop	Updates a value indicating if the sample should be looped.
getLoop	Returns a value indicating if the sample is looped.
setMaxDistance	Updates a distance, at which the sound completely fades out, in units.
getMaxDistance	Returns a distance, at which the sound completely fades out, in units.
setMinDistance	Updates a distance, at which the sound starts to fade, in units.
getMinDistance	Returns a distance, at which the sound starts to fade, in units.
setOcclusion	Updates a value indicating if the sound source should be muffled when being occluded.
getOcclusion	Returns a value indicating if sound source should be muffled when being occluded.
setOcclusionMask	Updates the bit mask, that determines which objects occlude the sound source.
getOcclusionMask	Returns the current bit mask that determines which objects occlude the sound source.
setPitch	Updates a sound pitch.
getPitch	Returns the current sound pitch.
isPlaying	Returns a value indicating if the sample is currently being played.
setPlayOnEnable	Enables or disables playback start on enabling the sound source.
isPlayOnEnable	Returns a value indicating if playback is to be started each time the sound source is enabled.
setRestartOnEnable	Enables or disables playback restart on enabling the sound source.
isRestartOnEnable	Returns a value indicating if playback is to be restarted from the beginning each time the sound source is enabled.
setReverbMask	Updates the bit mask that determines what reverberation zones can be heard.
getReverbMask	Returns the current bit mask that determines what reverberation zones can be heard.
setRoomRolloff	Updates the scaling room rolloff factor for the sound source that determines attenuation of the reverberation sound over distance.
getRoomRolloff	Returns the current scaling room rolloff factor for the sound source that determines attenuation of the reverberation sound over distance.
setSampleName	Sets a new sound file for the ambient sound.
getSampleName	Returns the sound sample file of the sound source.
setSourceMask	Updates a bit mask that determines to what sound channels the source belongs to.
getSourceMask	Returns a bit mask that determines to what sound channels the source belongs to.
isStopped	Returns a value indicating if playback is currently stopped.
setStream	Set a value indicating whether the sound is streamed or not.
isStream	Returns a value indicating whether the sound is streamed or not.
setTime	Updates time, from which the sample should be played.
getTime	Returns the current time, at which the sample is being played.
setAdaptation	Sets the new adaptation time period for the sound source, during which the volume of the occluded sound gradually changes (fading in and out).
getAdaptation	Returns the current adaptation time period for the sound source, during which the volume of the occluded sound gradually changes (fading in and out).
play	Starts playing the sample.
stop	Stops playback.
type	Returns the type of the node.

SoundSource Class

Members

static SoundSourcePtr create ( const char * name, int stream = 0 ) #

Constructor. Creates a new world sound source using a given sound sample file.

Arguments

const char * name - Path to the sound sample file.
int stream - Positive value to create a streaming source, 0 to create a static source. If the flag is set, the sample will not be fully loaded into memory. Instead, its successive parts will be read one by one into a memory buffer.

void setAirAbsorption ( float absorption ) #

Updates the air absorption value for the sound source that determines the distance-dependent attenuation of the reverberation sound at high frequencies caused by the propagation medium.

Arguments

float absorption - Air absorption value in range [0.0;10.0].

float getAirAbsorption ( ) #

Returns the current air absorption value for the sound source that determines the distance-dependent attenuation of the reverberation sound at high frequencies caused by the propagation medium.

Return value

Air absorption value.

void setConeInnerAngle ( float angle ) #

Updates an angle of the inner sound cone. Sound volume in the inner cone does not change. 360 degrees represents an omnidirectional sound source.

Arguments

float angle - Cone inner angle in degrees.

float getConeInnerAngle ( ) #

Returns the current angle of the inner sound cone. Sound volume in the inner cone does not change.

Return value

Cone inner angle in degrees.

void setConeOuterAngle ( float angle ) #

Updates an angle of the outer sound cone. When moving to the edge of the outer cone, sound volume is fading up to the gain value outside the oriented cone.

Arguments

float angle - Cone outer angle in degrees.

float getConeOuterAngle ( ) #

Returns the current angle of the outer sound cone. When moving to the edge of the outer cone, sound volume is fading up to the outside the cone gain value.

Return value

Cone outer angle in degrees.

void setConeOuterGain ( float gain ) #

Updates the gain controlling the sound intensity outside the oriented cone defined by the outer angle.

Arguments

float gain - Cone outer gain in range [0.0;1.0].

float getConeOuterGain ( ) #

Returns the current gain controlling the sound intensity outside the oriented cone defined by the outer angle.

Return value

Cone outer gain.

void setConeOuterGainHF ( float coneoutergainhf ) #

Updates the gain filter value for the sound source that attenuates the reverberation sound at high frequencies outside the oriented cone.

Arguments

float coneoutergainhf - High-frequency reverberation gain value in range [0.0;1.0].

float getConeOuterGainHF ( ) #

Returns the current gain filter value for the sound source that attenuates the reverberation sound at high frequencies outside the oriented cone.

Return value

High-frequency reverberation gain value.

void setGain ( float gain ) #

Updates the gain controlling the sound intensity. Setting the value to 0.0 mutes the sound source.

Arguments

float gain - Gain value in range [0.0;1.0].

void setOcclusionMask ( int mask ) #

Updates the bit mask, that determines which objects occlude the sound source. For a sound to be occluded by an object's surface, at least one bit of this mask should match the occlusion mask of object's surface. Each surface has its own occlusion value, that determines how much it affects sounds in case of occlusion.

Notice

Sound occlusion must be enabled.

Arguments

int mask - Integer, each bit of which is a mask for sound source occlusion.

int getOcclusionMask ( ) #

Returns the current bit mask that determines which objects occlude the sound source. For a sound to be occluded by an object's surface, at least one bit of this mask should match the occlusion mask of object's surface. Each surface has its own occlusion value, that determines how much it affects sounds in case of occlusion.

Notice

Playback will begin from the moment it was previously stopped. To enable playback from the beginning use the setRestartOnEnable() method.

Arguments

int enable - 1 to enable playback start on enabling the sound source, 0 to disable it.

int isPlayOnEnable ( ) #

Returns a value indicating if playback is to be started each time the sound source is enabled.

Notice

Playback will begin from the moment it was previously stopped. To enable playback from the beginning use the setRestartOnEnable() method.

Return value

1 if playback is to be started each time the sound source is enabled; otherwise, 0.

void setRestartOnEnable ( int enable ) #

Enables or disables playback restart on enabling the sound source.

Arguments

int enable - 1 to enable playback restart on enabling the sound source, 0 to disable it.

int isRestartOnEnable ( ) #

Returns a value indicating if playback is to be restarted from the beginning each time the sound source is enabled.

Return value

1 if playback is to be restarted from the beginning each time the sound source is enabled; otherwise, 0.

void setReverbMask ( int mask ) #

Updates the bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match with the player's reverberation mask. At the same time, reverb mask of the reverberation zone should also match with the player's one (but not necessarily in the same bit as this mask matches it).

Arguments

int mask - Integer, each bit of which is a mask for reverberating sound sources.

int getReverbMask ( ) #

Returns the current bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match with the player's reverberation mask. At the same time, reverb mask of the reverberation zone should also match with the player's one (but not necessarily in the same bit as this mask matches it).

Return value

Integer, each bit of which is a mask for reverberating sound sources.

void setRoomRolloff ( float rolloff ) #

Updates the scaling room rolloff factor for the sound source that determines attenuation of the reverberation sound over distance.

Arguments

float rolloff - Room rolloff factor in range [0.0; 10.0].

float getRoomRolloff ( ) #

Returns the current scaling room rolloff factor for the sound source that determines attenuation of the reverberation sound over distance.

Return value

Room rolloff factor.

void setSampleName ( const char * name ) #

Sets a new sound file for the ambient sound.

Arguments

const char * name - Path to the sound sample file.

const char * getSampleName ( ) #

Returns the sound sample file of the sound source.

Return value

Path to the sound sample file.

void setSourceMask ( int mask ) #

Updates a bit mask that determines to what sound channels the source belongs to. For a sound source to be heard, its mask should match with the player's sound mask in at least one bit.

Arguments

int mask - Integer, each bit of which specifies a sound channel.

int getSourceMask ( ) #

Returns a bit mask that determines to what sound channels the source belongs to. For a sound source to be heard, its mask should match at least with the player's sound mask in at least one bit.

Return value

Integer, each bit of which specifies a sound channel.

int isStopped ( ) #

Returns a value indicating if playback is currently stopped.

Return value

1 if the sample is stopped; otherwise, 0.

void setStream ( int stream ) #

Set a value indicating whether the sound is streamed or not.

Arguments

int stream - 1 if the sound is a streamed one; otherwise, 0.

int isStream ( ) #

Returns a value indicating whether the sound is streamed or not.

Return value

1 if the sound is a streamed one; otherwise, 0.

void setTime ( float time ) #

Updates time, from which the sample should be played.

Notice

This function is ineffective if the sample is already playing. At first it is necessary to stop the playback, set the time, and then resume the playback.

Arguments

float time - Time in seconds.

float getTime ( ) #

Returns the current time, at which the sample is being played.

Return value

Time in seconds.

void play ( ) #

Starts playing the sample.

void stop ( ) #

Stops playback. This function saves the playback position so that playing of the file can be resumed from the same point.

Notice

The playback won't stop immediately, as the sound thread is updated at 30 FPS. So, when you need to perform operations that require stopping of the playback (for example, updating the time, from which the sample should be played), you need to force update the sound thread after stopping the playback.

static int type ( ) #

Returns the type of the node.

Return value

Sound type identifier.

void setAdaptation ( float adaptation ) #

Sets the new adaptation time period for the sound source, during which the volume of the occluded sound gradually changes (fading in and out). This parameter is used to make sounds fade in and out smoothly.

Arguments

float adaptation - Adaptation time to be set, in seconds. 0.0f means instant adaptation.

float getAdaptation ( ) #

Returns the current adaptation time period for the sound source, during which the volume of the occluded sound gradually changes (fading in and out). This parameter is used to make sounds fade in and out smoothly.

Return value

Current adaptation time, in seconds. 0.0f means instant adaptation.

Last update: 2019-12-25

Help improve this article

Was this article helpful?

Report a problem related to this article

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

Unigine::SoundSource Class

Creating a Sound Source#

Updating an Existing Sound Source#

See Also

Methods:

SoundSource Class

Members

static SoundSourcePtr create ( const char * name, int stream = 0 ) #

Arguments

void setAirAbsorption ( float absorption ) #

Arguments

float getAirAbsorption ( ) #

Return value

void setConeInnerAngle ( float angle ) #

Arguments

float getConeInnerAngle ( ) #

Return value

void setConeOuterAngle ( float angle ) #

Arguments

float getConeOuterAngle ( ) #

Return value

void setConeOuterGain ( float gain ) #

Arguments

float getConeOuterGain ( ) #

Return value

void setConeOuterGainHF ( float coneoutergainhf ) #

Arguments

float getConeOuterGainHF ( ) #

Return value

void setGain ( float gain ) #

Arguments

float getGain ( ) #

Return value

float getLength ( ) #

Return value

void setLoop ( int loop ) #

Arguments

int getLoop ( ) #

Return value

void setMaxDistance ( float distance ) #

Arguments

float getMaxDistance ( ) #

Return value

void setMinDistance ( float distance ) #

Arguments

float getMinDistance ( ) #

Return value

void setOcclusion ( int occlusion ) #

Arguments

int getOcclusion ( ) #

Return value

void setOcclusionMask ( int mask ) #

Arguments

int getOcclusionMask ( ) #

Return value

void setPitch ( float pitch ) #

Arguments

float getPitch ( ) #

Return value

int isPlaying ( ) #

Return value

void setPlayOnEnable ( int enable ) #

Arguments

int isPlayOnEnable ( ) #

Return value

void setRestartOnEnable ( int enable ) #

Arguments

int isRestartOnEnable ( ) #

Return value

void setReverbMask ( int mask ) #

Arguments

int getReverbMask ( ) #

Return value

void setRoomRolloff ( float rolloff ) #

Arguments

float getRoomRolloff ( ) #

Return value

void setSampleName ( const char * name ) #

Arguments

const char * getSampleName ( ) #