This page has been translated automatically.
视频教程
界面
要领
高级
实用建议
专业(SIM)
UnigineEditor
界面概述
资源工作流程
版本控制
设置和首选项
项目开发
调整节点参数
Setting Up Materials
设置属性
照明
Sandworm
使用编辑器工具执行特定任务
如何擴展編輯器功能
嵌入式节点类型
Nodes
Objects
Effects
Decals
光源
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
编程
基本原理
搭建开发环境
使用范例
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
材质和着色器
Rebuilding the Engine Tools
GUI
双精度坐标
应用程序接口
Animations-Related Classes
Containers
Common Functionality
Controls-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
VR-Related Classes
创建内容
内容优化
材质
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Unigine::Sound Class

Header: #include <UnigineSounds.h>

Controls the general sound settings, such as volume, speed of sound, the Doppler factor, sound adaptation and sound mixer channels. Settings can be loaded from a *.sound file or changed by the corresponding functions below.

In the *.sound file, the sound settings are stored in the <sound> section, for example:

Source code (XML)
<?xml version="1.0" encoding="utf-8"?>
<settings version="2.16.0.2">
	<sound>
		<enabled>1</enabled>
		<sound_manager_load_samples>0</sound_manager_load_samples>
		<sound_manager_sample_static_memory>64</sound_manager_sample_static_memory>
		<sound_manager_sample_stream_memory>16</sound_manager_sample_stream_memory>
		<sound_reverb>2</sound_reverb>
		<sound_occlusion>1</sound_occlusion>
		<al_sound_skip_errors>0</al_sound_skip_errors>
		<scale>1</scale>
		<volume>1</volume>
		<doppler>1</doppler>
		<velocity>343.299988</velocity>
		<adaptation>1</adaptation>
		<attenuation>3</attenuation>
		<hrtf>0</hrtf>
		<source source="0" limit="2"/>
		<source source="1" limit="4"/>
		<source source="2" limit="4"/>
		<source source="4" volume="0.4"/>
	</sound>
</settings>

Usage Example#

The following example shows how to load sound settings from the *.world file, change them and then save back to the sound settings file. Settings are loaded at startup. While the sound source (AmbientSource) is playing, you can use keyboard to change sound volume, toggle sounds on and off, and display current velocity. On shutdown the current sound settings are saved.

AppWorldLogic.cpp

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineGame.h>
#include <UnigineLog.h>
#include <UnigineProfiler.h>
#include <UnigineSounds.h>

using namespace Unigine;

AmbientSourcePtr source;

int AppWorldLogic::init()
{
	// load sound settings from a file
	Sound::loadSettings("sound_settings.sound");

	// create a sound source that plays a sample
	source = AmbientSource::create("sounds/ambient_source.oga", 1);
	source->setLoop(1);
	source->play();

	return 1;
}

int AppWorldLogic::update()
{
	// enable/disable sounds in the scene
	if (Input::isKeyPressed(Input::KEY_Z)) {
		Sound::setEnabled(!Sound::isEnabled());
		Log::message("The enabled flag is %d\n", Sound::isEnabled());
	}

	// print the current speed of sound
	if (Input::isKeyPressed(Input::KEY_C)) {
		Log::message("Sound velocity: %f\n", Sound::getVelocity());
	}

	// make the sound louder
	if (Input::isKeyPressed(Input::KEY_N)) {
		if (Sound::getVolume() != 1.0f) Sound::setVolume(Sound::getVolume() + 0.1f);
		Log::message("The sound is louder %f\n", Sound::getVolume());
	}

	// make the sound lower
	if (Input::isKeyPressed(Input::KEY_M)) {
		if (Sound::getVolume() > 0.0f) Sound::setVolume(Sound::getVolume() - 0.1f);
		Log::message("The sound is quieter %f\n", Sound::getVolume());
	}
	
	return 1;
}

int AppWorldLogic::shutdown()
{
	// save the sound settings into the file
	Sound::saveSettings("sound_settings.sound", 1); 
	
	return 1;
}

Sound Class

Members


void setAdaptation ( float adaptation ) #

Sets sound occlusion with the specified adaptation time.

Arguments

  • float adaptation - Time for sound adaptation to a filter, used when the sound source becomes occluded or other way round.

float getAdaptation ( ) #

Returns the current time set for sound adaptation, that is used when the sound source becomes occluded or other way round.

Return value

Time for sound adaptation to a filter.

void setAttenuation ( int attenuation ) #

Sets the specified sound attenuation mode. Attenuation is the ability of a sound to lower in volume as the player moves away from it.

Arguments

int getAttenuation ( ) #

Returns the current sound attenuation mode.

Return value

One of the ATTENUATION_* variables.

void setData ( const char * data ) #

Sets user data associated with the world. This string is written directly into a *.world file, into the data child tag of the sound tag, for example:
Source code (XML)
<world version="2.16.0.2">

	<sound>
		<data>User data</data>
	</sound>

</world>

Arguments

  • const char * data - New user data. Data can contain an XML formatted string

const char * getData ( ) #

Returns user string data associated with the world. This string is written directly into the data tag of the *.world file, into the data child tag of the sound tag, for example:
Source code (XML)
<world version="2.16.0.2">

	<sound>
		<data>User data</data>
	</sound>

</world>

Return value

User data. Data can contain an XML formatted string.

void setDoppler ( float doppler ) #

Sets the Doppler factor. This parameter allows you to exaggerate or tone-down the Doppler shift effect. By default, it is set to 1.0f.

Arguments

  • float doppler - Doppler factor.

float getDoppler ( ) #

Returns the current Doppler factor. This parameter allows you to exaggerate or tone-down the Doppler shift effect. The default value is 1.0f.

Return value

Doppler factor.

void setEnabled ( int enabled ) #

Enables or disables all sounds in the scene.

Arguments

  • int enabled - 1 to enable all sounds, 0 to disable them.

int isEnabled ( ) #

Returns a value indicating if sounds in the scene are enabled.

Return value

1 if sounds are enabled; otherwise, 0.

void setHRTF ( int hrtf ) #

Enables or disables the HRTF (Head Related Transfer Function) mode. This mode provides imitation of the surround sound for the stereo wired headset.

Arguments

  • int hrtf - 1 to enable binaural sound; 0 to disable it.

int isHRTF ( ) #

Returns a value indicating if the binaural HRTF (Head Related Transfer Function) sound is enabled. An HRTF provides imitation of the surround sound for the stereo wired headset.

Return value

1 if the binaural sound is enabled; otherwise, 0.

void setSourceReverbMode ( int mode ) #

Sets sound reverberation mode.

Arguments

int getSourceReverbMode ( ) #

Returns current sound reverberation mode.

Return value

Current sound reverberation mode. One of the REVERB_* variables. The default value is REVERB_MULTIPLE.

void setSourceOcclusion ( int occlusion ) #

Enables or disables occlusion for sounds. When enabled, the sound will be occluded when there are other nodes between the listener and the sound source.

Arguments

  • int occlusion - 1 to enable occlusion for sounds, 0 to disable it.

int isSourceOcclusion ( ) #

Returns a value indicating if occlusion for sounds is enabled. When enabled, the sound will be occluded when there are other nodes between the listener and the sound source.

Return value

1 if sound occlusion for sounds is enabled; otherwise, 0.

void setScale ( float scale ) #

Set the time scale for the sound playing.

Arguments

  • float scale - Sound time scale. The provided value is clamped in the range [0; 2].

float getScale ( ) #

Returns the current time scale for the sound playing.

Return value

Sound time scale.

void setSourceLimit ( int source, int limit ) #

Limits the number of simultaneously played sound sources per one mixer channel. This setting is also available in the Editor global sound settings.

Arguments

  • int source - Number of the mixer channel (from 0 to 31).
  • int limit - The maximum number of sound sources that can be played simultaneously.

int getSourceLimit ( int source ) #

Returns the current number of simultaneously played sound sources per one mixer channel.

Arguments

  • int source - Number of the mixer channel (from 0 to 31).

Return value

The maximum number of sound sources that can be played simultaneously.

void setSourceVolume ( int source, float volume ) #

Sets the volume of the specified mixer channel.

Arguments

  • int source - Number of the mixer channel (from 0 to 31).
  • float volume - Channel volume. The provided value is clamped within [0;1] range, where 0 means muted sound and 1 is the maximum volume.

float getSourceVolume ( int source ) #

Returns the current volume of the specified mixer channel.

Arguments

  • int source - Number of the mixer channel (from 0 to 31).

Return value

Volume of the specified mixer channel. The returning value is in range [0;1], where 0 means muted sound and 1 is the maximum volume.

float getTotalTime ( ) #

Returns the total time of asynchronous loading sounds.

Return value

The total time value, milliseconds.

void setVelocity ( float velocity ) #

Sets the velocity value the Doppler shift calculation is based upon. By default, it is set to 343.3f. If you have players moving really fast, then you may want to adjust this to prevent the Doppler shift from distorting the sound too much.

Arguments

  • float velocity - New velocity value for the Doppler shift calculation to be set.

float getVelocity ( ) #

Returns the current velocity value the Doppler shift calculation is based upon. By default, it is set to 343.3f. If you have players moving really fast, then you may want to adjust this to prevent the Doppler shift from distorting the sound too much.

Return value

Current velocity value for the Doppler shift calculation.

void setVolume ( float volume ) #

Sets the sound volume. By default, it is set to 1.0f.

Arguments

  • float volume - Sound volume. 0 means the muted sound, 1 means the maximum volume.

float getVolume ( ) #

Returns the current sound volume. The default value is 1.0f.

Return value

Sound volume. 0 means the muted sound, 1 means the maximum volume.

int loadSettings ( const char * name, bool clear = false ) #

Loads the sound settings from the given file.

Arguments

  • const char * name - Path to a sound settings file (*.sound).
  • bool clear - Clear flag. Set true to clear settings before loading (new settings shall be applied right after loading them), or false not to clear.

Return value

1 if the sound settings are loaded successfully; otherwise, 0.

int loadWorld ( const Ptr<Xml> & xml ) #

Loads a sound state from the Xml. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Arguments

  • const Ptr<Xml> & xml - Xml smart pointer.

Return value

1 if the sound state is loaded successfully; otherwise, 0.

void renderWorld ( int force ) #

Forces update of the sound system: all sound changes (such as play() or stop() events and change of parameters) will be applied at once. The sound thread is updated at 30 FPS. Imagine, you have a sound sample playing and you want to update the time, from which the sample should be played. But playback won't stop immediately, so the a new time value won't be set. You need force updating of the sound thread after stopping it:
Source code (C++)
AmbientSourcePtr sound = AmbientSource::create("ambient_sample.oga");
// ...
// 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(45.0f);
	// continue playing the sample 
	sound->play();
}

Arguments

  • int force - 1 to force update of the sound system; otherwise, 0.

int saveSettings ( const char * name, int force = 0 ) #

Saves the current sound settings to the given file.

Arguments

  • const char * name - Path to a sound settings file (*.sound).
  • int force - Force flag indcating if forced saving of sound settings is enabled.

Return value

true if the sound settings are saved successfully; otherwise, false.

bool saveState ( const Ptr<Stream> & stream ) #

Saves a sound state into the stream. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Example using saveState() and restoreState() methods:

Source code (C++)
// create a sound source that plays a sample and set its state
source = AmbientSource::create("sounds/ambient_source.oga", 1);
Unigine::Sound::setScale(0.75f);

// save state
BlobPtr blob_state = Blob::create();
Unigine::Sound::saveState(blob_state);

// change state
Unigine::Sound::setScale(1.25f);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
Unigine::Sound::restoreState(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the sound state is saved successfully; otherwise, false.

int restoreState ( const Ptr<Stream> & stream ) #

Restores a sound state from the stream. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Example using saveState() and restoreState() methods:

Source code (C++)
// create a sound source that plays a sample and set its state
source = AmbientSource::create("sounds/ambient_source.oga", 1);
Unigine::Sound::setScale(0.75f);

// save state
BlobPtr blob_state = Blob::create();
Unigine::Sound::saveState(blob_state);

// change state
Unigine::Sound::setScale(1.25f);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
Unigine::Sound::restoreState(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the sound state is restored successfully; otherwise, false.

int saveWorld ( const Ptr<Xml> & xml, int force = 0 ) #

Saves a sound state into the given Xml node. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Arguments

  • const Ptr<Xml> & xml - Xml smart pointer.
  • int force - Force flag indicating if forced saving of the sound state is enabled.

Return value

true if the sound state is saved successfully; otherwise, false.
Last update: 2023-02-28
Build: ()