Unigine::AmbientSource Class

Header:

#include <UnigineSounds.h>

This class is used to create a non-directional ambient background sound.

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 should be created in the system script unigine.usc; otherwise, no sound will be heard.

Creating an Ambient Sound Source#

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

Source code (C++)

// 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::get()->setPlayer(player->getPlayer());

// create the ambient sound source
AmbientSourcePtr sound = AmbientSource::create("sound.mp3");
// set necessary sound settings
sound->setGain(0.5f);
sound->setPitch(10.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:

Source code (C++)

// change the sample file of the playing sound source
if ((sound->isPlaying()) && (App::get()->clearKeyState('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:

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::get()->renderWorld(1);
	// update time
	sound->setTime(0.0f);
	// play the sample 
	sound->play();
}

Methods:

Name	Description View: Sort by:
*create*	Constructor.
grab	Grabs the node (sets the owner flag to 1).
release	Releases the node (sets the owner flag to 0).
isOwner	Returns the owner flag.
setGain	Sets volume of the sound.
getGain	Returns volume of the sound.
getInterface
getLength	Returns the total length of the sound sample.
setLoop	Sets a value indicating if the sample should be looped.
getLoop	Returns a value indicating if the sample is looped.
setPitch	Sets a sound pitch.
getPitch	Returns a sound pitch.
isPlaying	Returns a value indicating if the sample is being played.
setSampleName	Sets a new sound file for the ambient sound.
getSampleName	Returns the name of the sound file.
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 stopped.
setTime	Sets time, from which the sample should be played.
getTime	Returns the current time, at which the sample is being played.
play	Starts playing the sample.
stop	Stops playback.

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 grab( )

Grabs the node (sets the owner flag to 1). The node should not be handled by the engine after this function is called. For more information on managing ownership, please refer to the Memory Management article.

void release( )

Releases the node (sets the owner flag to 0). The node should be handled by the engine after this function is called. For more information on managing ownership, please refer to the Memory Management article.

int isOwner( )

Returns the owner flag. If the pointer is the owner, on its deletion the node also will be deleted. Use grab() and release() functions to change ownership. For more information on managing ownership, please refer to the Memory Management article.

Return value

Owner flag

void setGain( float gain )

Sets volume of the sound.

Arguments

float gain - Volume. 0 means muted, 1 means maximum volume.

float getGain( )

Returns volume of the sound.

Return value

Volume. 0 means muted, 1 means maximum volume.

void * getInterface( )

float getLength( )

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

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

Returns a sound pitch.

Return value

Factor, by which the current pitch will be multiplied.

int isPlaying( )

Returns a value indicating if the sample is being played.

Return value

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

void setSampleName( const char * name )

Sets a new sound file for the ambient sound.

Notice

To change the sound file of the currently played ambient sound, first, you should stop the playback, set the sample name, and then resume the playback.

Source code (C++)

if (sound->isPlaying())
{
	// stop the playing sound
	sound->stop();
	// force updating of the sound thread
	Sound::get()->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( )

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

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

Return value

1 if the sample is stopped; otherwise, 0.

void setTime( float time )

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

Last update: 27.12.2018

Помогите сделать статью лучше

Была ли эта статья полезной?

Сообщить о проблеме в этой статье

(или выберите слово/фразу и нажмите Ctrl+Enter