SoundSource Class

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

Sound sources are automatically handled by the sound manger. 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.

SoundSource Class

This class inherits from Node

Members

---

SoundSource (string name, int stream = 0)

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

Arguments

• string name - Path to the sound sample file.
• int stream = 0 - 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.

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.

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.

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.

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.

float getConeOuterGain ()

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

Return value

Cone outer gain.

float getGain ()

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

Return value

Gain value.

float getLength ()

Returns the total length of the sound sample.

Return value

Length of the sample in seconds.

int getLoop ()

Returns a value indicating if the sample is looped.

Return value

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

float getMaxDistance ()

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

Return value

Distance in units.

float getMinDistance ()

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

Return value

Distance in units.

int getOcclusion ()

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.

float getPitch ()

Returns the current sound pitch.

Return value

Factor, by which the pitch is multiplied.

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.

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.

string getSampleName ()

Returns the sound sample file of the sound source.

Return value

Path to the sound sample file.

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.

float getTime ()

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

Return value

Time in seconds.

int isPlaying ()

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

Return value

1 if the sample is being played; otherwise, 0.

int isStopped ()

Returns a value indicating if playback is currently stopped.

Return value

1 if the sample is stopped; otherwise, 0.

void play ()

Starts playing the sample.

void setAirAbsorption (float gain)

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. The default is 0.0.

Arguments

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

void setConeInnerAngle (float angle)

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

Arguments

• float angle - 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. The default is 360 degrees.

Arguments

• float angle - Cone outer angle in degrees.

void setConeOuterGainHF (float gain)

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

Arguments

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

void setConeOuterGain (float gain)

Updates the gain controlling the sound intensity outside the oriented cone defined by the outer angle. The default is 0.

Arguments

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

void setGain (float gain)

Updates the gain controlling the sound intensity. Setting the value to 0.0 mutes the sound source. The default is 1.0.

Arguments

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

void setLoop (int mode)

Updates a value indicating if the sample should be looped. The default is 0.

Arguments

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

void setMaxDistance (float distance)

Updates a distance, at which the sound completely fades out, in units. The default is 1.0 units.

Arguments

• float distance - Distance in units.

void setMinDistance (float distance)

Updates a distance, at which the sound starts to fade, in units. The default is 0 units.

Arguments

• float distance - Distance in units.

void setOcclusion (int occlusion)

Updates a value indicating if the sound source should be muffled when being occluded. The default is 1.

Arguments

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

void setPitch (float pitch)

Updates a sound pitch. The default is 1.

Arguments

• float pitch - Factor, by which the current pitch will be multiplied in range [0.1;10.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.

void setRoomRolloff (float rolloff)

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

Arguments

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

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.

void setTime (float time)

Updates time, from which the sample should be played.

Arguments

• float time - Time in seconds.

void stop ()

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