Unigine::SoundSource Class

// 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();

// 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);
}

// 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();
}

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 ( ) const#

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 ( ) const#

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 ( ) const#

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 ( ) const#

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 ( ) const#

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

float getGain ( ) const#

Returns the current gain controlling the sound intensity. Is set to 0, the sound source is muted.

Return value

Gain value.

float getLength ( ) const#

Returns the total length of the sound sample.

Return value

Length of the sample in seconds.

void setLoop ( int loop ) #

Updates a value indicating if the sample should be looped.

Arguments

• int loop - Positive number to loop the sample, 0 to play it only once.

int getLoop ( ) const#

Returns a value indicating if the sample is looped.

Return value

Positive number if the sample is currently looped; otherwise, 0.

void setMaxDistance ( float distance ) #

Updates a distance, at which the sound completely fades out, in units.

Arguments

• float distance - Distance in units.

float getMaxDistance ( ) const#

Returns a distance, at which the sound completely fades out, in units.

Return value

Distance in units.

void setMinDistance ( float distance ) #

Updates a distance, at which the sound starts to fade, in units.

Arguments

• float distance - Distance in units.

float getMinDistance ( ) const#

Returns a distance, at which the sound starts to fade, in units.

Return value

Distance in units.

void setOcclusion ( int occlusion ) #

Updates a value indicating if the sound source should be muffled when being occluded.

Arguments

• int occlusion - Positive number if the sound should be muffled by occlusion; otherwise, 0.

int getOcclusion ( ) const#

Returns a value indicating if sound source should be muffled when being occluded.

Return value

Positive number if the sound is muffled by occlusion; otherwise, 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.

Arguments

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

int getOcclusionMask ( ) const#

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.

Return value

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

void setPitch ( float pitch ) #

Updates a sound pitch.

Arguments

• float pitch - Factor, by which the current pitch will be multiplied in range [0.1;10.0].

float getPitch ( ) const#

Returns the current sound pitch.

Return value

Factor, by which the pitch is multiplied.

bool isPlaying ( ) const#

Returns a value indicating if the sample is currently being played.

Return value

true if the sample is being played; otherwise, false.

void setPlayOnEnable ( bool enable ) #

Enables or disables playback start on enabling the sound source.

Arguments

• bool enable - true to enable playback start on enabling the sound source, false to disable it.

bool isPlayOnEnable ( ) const#

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

Return value

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

void setRestartOnEnable ( bool enable ) #

Enables or disables playback restart on enabling the sound source.

Arguments

• bool enable - true to enable playback restart on enabling the sound source, false to disable it.

bool isRestartOnEnable ( ) const#

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

Return value

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

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 ( ) const#

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 ( ) const#

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 ( ) const#

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 ( ) const#

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.

bool isStopped ( ) const#

Returns a value indicating if playback is currently stopped.

Return value

true if the sample is stopped; otherwise, false.

void setStream ( bool stream ) #

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

Arguments

• bool stream - true if the sound is a streamed one; otherwise, false.

bool isStream ( ) const#

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

Return value

true if the sound is a streamed one; otherwise, false.

void setTime ( float time ) #

Updates time, from which the sample should be played.

Arguments

• float time - Time in seconds.

float getTime ( ) const#

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 doesn't reset the playback position so that playing of the file can be resumed from the same point.

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 ( ) const#

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.