Unigine::AmbientSource Class
Header: | #include <UnigineSounds.h> |
This class is used to create a non-directional ambient background sound.
Creating an Ambient Sound Source#
To create an ambient sound source, create an instance of the AmbientSource class and specify all required settings:
// create a player so that an ambient sound source is played
PlayerSpectatorPtr player = PlayerSpectator::create();
player->setPosition(Vec3(0.0f, -3.401f, 1.5f));
player->setViewDirection(vec3(0.0f, 1.0f, -0.4f));
Game::setPlayer(player);
// create the ambient sound source
AmbientSourcePtr sound = AmbientSource::create("sound.mp3");
// set necessary sound settings
sound->setGain(0.5f);
sound->setPitch(1.0f);
sound->setLoop(1);
sound->play();
Updating an Existing Ambient Sound Source#
To update the settings of the ambient sound source, you can simply call the corresponding methods:
// change the sample file of the playing sound source
if ((sound->isPlaying()) && (Input::isKeyDown(Input::KEY::KEY_C)))
{
// increase the pitch
sound->setPitch(2.0f);
// 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, or the sample name), you need to force update the sound thread after stopping the playback:
// 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();
}
See Also#
- Controlling Sound Sources Globally article to learn how to toggle all sounds at the same time
-
A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/sounds/ folder:
- ambient_static_00
- ambient_static_01
- ambient_stream_00
- ambient_stream_01
- Sounds sample in C# Component Samples suite
AmbientSource Class
Members
static AmbientSourcePtr create ( const char * name, int stream = 0 ) #
Constructor. Creates a new ambient sound source using a given sound file.Arguments
- const char * name - Path to the sound 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 setGain ( float gain ) #
Sets volume of the sound.Arguments
- float gain - Volume. 0 means muted, 1 means maximum volume.
float getGain ( ) const#
Returns volume of the sound.Return value
Volume. 0 means muted, 1 means maximum volume.float getLength ( ) const#
Returns the total length of the sound sample.Return value
Length of the sample in seconds.void setLoop ( int loop ) #
Sets 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 looped; otherwise, 0.void setPitch ( float pitch ) #
Sets a sound pitch.Arguments
- float pitch - Factor, by which the current pitch will be multiplied.
float getPitch ( ) const#
Returns a sound pitch.Return value
Factor, by which the current pitch will be multiplied.bool isPlaying ( ) const#
Returns a value indicating if the sample is being played.Return value
true if the sample is being played; otherwise, false.void setSampleName ( const char * name ) #
Sets a new sound file for the ambient sound.if (sound->isPlaying())
{
// stop the playing sound
sound->stop();
// force updating of the sound thread
Sound::renderWorld(1);
// set a new sample file to be played
sound->setSampleName("stream_stereo_01.oga");
// play the sound
sound->play();
}
Arguments
- const char * name - Path to the sound file.
const char * getSampleName ( ) const#
Returns the name of the sound file.Return value
Path to the sound 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 stopped.Return value
true if the sample is stopped; otherwise, false.void setTime ( float time ) #
Sets time, from which the sample should be played.Arguments
- float time - Time in seconds.