Unigine.AmbientSource Class
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:
Notice
For an ambient source to be played, a player is always required. In case an ambient source needs to be played when neither a world, nor the editor are loaded, a player, as well as the sound source (see code below), should be created in the SystemLogic.Init() method; otherwise, no sound will be heard.
Source code (C#)
// create a player so that an ambient sound source is played
PlayerSpectator player = new PlayerSpectator();
player.Position = new Vec3(0.0f, -3.401f, 1.5f);
player.ViewDirection = new vec3(0.0f, 1.0f, -0.4f);
Game.Player = player;
// create the ambient sound source
AmbientSource sound = new AmbientSource("sound.mp3");
// set necessary sound settings
sound.Gain = 0.5f;
sound.Pitch = 1.0f;
sound.Loop = 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:
Source code (C#)
// change the sample file of the playing sound source
if ((sound.IsPlaying) && (App.ClearKeyState('c') == 1))
{
// increase the pitch
sound.Pitch = 2.0f;
// reduce the gain
sound.Gain = 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:
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.Time = 0.0f;
// play the sample
sound.Play();
}See Also#
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
AmbientSource Class
Properties
bool IsStopped#
A value indicating if playback is stopped.
bool IsPlaying#
A value indicating if the sample is being played.
float Time#
The current time, at which the sample is being played.
set
int SourceMask#
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.
set
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.
set value -
Integer, each bit of which specifies a sound channel.
string SampleName#
The name of the sound file.
set
Sets a new sound file for the ambient sound.
Notice
Source code (C#)
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.SampleName = "stream_stereo_01.oga";
// play the sound
sound.Play();
}set value -
Path to the sound file.
float Pitch#
A sound pitch.
set
Sets a sound pitch.
set value -
Factor, by which the current pitch will be multiplied.
int Loop#
A value indicating if the sample is looped.
set
Sets a value indicating if the sample should be looped.
set value -
Positive number to loop the sample, 0 to play it only once.
float Length#
The total length of the sound sample.
float Gain#
Volume of the sound.
set
Sets volume of the sound.
set value -
Volume. 0 means muted, 1 means maximum volume.
Members
static AmbientSource ( string name, int stream = 0 ) #
Constructor. Creates a new ambient sound source using a given sound file.Arguments
- string 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 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.
Last update:
2020-11-20
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)