Castle Game Engine

Class TSoundAllocator

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TSoundAllocator = class(TObject)

Description

Manager of allocated sounds.

For efficiency, the pool of available sound sources (things that are actually audible at a given time) is limited. This limit comes from the backend limits (like OpenAL or APIs underneath OpenAL), it may also come from sound hardware limitations, and in general you should not have too many playing sources, as mixing many sources is time-consuming. So you cannot simply allocate new sound source for each of 100 creatures you display in the game.

This class hides this limitation, by managing a pool of sound sources, and returning on demand the next unused sound source (or Nil). It can prioritize sound sources, it can reuse sound sources that finished playing, it can interrupt a lower-priority sound when necessary to play a higher-priority sound.

This is automatically used by higher-level comfortable methods to play sounds like TSoundEngine.Play.

Hierarchy

Overview

Fields

Public nested const DefaultMinAllocatedSources = 4;
Public nested const DefaultMaxAllocatedSources = 16;

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure Refresh; deprecated 'this does not do anything now; refreshing is done automatically if you use CastleWindow unit (with TCastleApplication, TCastleWindow) or TCastleControl; in other cases, you shoud call ApplicationProperties._Update yourself';
Public procedure LoadFromConfig(const Config: TCastleConfig); virtual; deprecated 'load sound properties explicitly from UserConfig';
Public procedure SaveToConfig(const Config: TCastleConfig); virtual; deprecated 'save sound properties explicitly to UserConfig';

Properties

Public property MinAllocatedSources: Cardinal read FMinAllocatedSources write SetMinAllocatedSources default DefaultMinAllocatedSources;
Public property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;
Public property InternalAllocatedSources: TInternalSoundSourceList read FAllocatedSources;

Description

Fields

Public nested const DefaultMinAllocatedSources = 4;
 
Public nested const DefaultMaxAllocatedSources = 16;
 

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public procedure Refresh; deprecated 'this does not do anything now; refreshing is done automatically if you use CastleWindow unit (with TCastleApplication, TCastleWindow) or TCastleControl; in other cases, you shoud call ApplicationProperties._Update yourself';

Warning: this symbol is deprecated: this does not do anything now; refreshing is done automatically if you use CastleWindow unit (with TCastleApplication, TCastleWindow) or TCastleControl; in other cases, you shoud call ApplicationProperties._Update yourself

 
Public procedure LoadFromConfig(const Config: TCastleConfig); virtual; deprecated 'load sound properties explicitly from UserConfig';

Warning: this symbol is deprecated: load sound properties explicitly from UserConfig

Load and save into the config file sound engine properties. For example use with UserConfig to store sound preferences along with other user preferences. Everything is loaded / saved under the path "sound/" inside Config.

TSoundAllocator saves MinAllocatedSources, MaxAllocatedSources. Descendant TSoundEngine additionally saves current Device, Enable (unless Enable was set by --no-sound command-line option). Descendant TRepoSoundEngine additionally saves sound and music volume.

This is deprecated, as in actual applications it is more obvious to just load/save the necessary sound properties explicitly. E.g. do this to load volume: 

Volume := UserConfig.GetFloat('sound/volume', 1.0);

Do this to save volume: 

UserConfig.SetDeleteFloat('sound/volume', Volume, 1.0);

This way you control which properties are saved. E.g. in most cases you don't need to save MinAllocatedSources, MaxAllocatedSources as most applications don't modify it. And it is your choice how to save music volume (in simplest case you can just load/save LoopingChannel[0].Volume, if you use LoopingChannel[0] for the music track).

Public procedure SaveToConfig(const Config: TCastleConfig); virtual; deprecated 'save sound properties explicitly to UserConfig';

Warning: this symbol is deprecated: save sound properties explicitly to UserConfig

 

Properties

Public property MinAllocatedSources: Cardinal read FMinAllocatedSources write SetMinAllocatedSources default DefaultMinAllocatedSources;

Minimum / maximum number of allocated sources. Always keep MinAllocatedSources <= MaxAllocatedSources.

For the sake of speed, we always keep allocated at least MinAllocatedSources sources. This must be >= 1. Setting MinAllocatedSources too large value will raise ENoMoreSources.

At most MaxAllocatedSources sources may be simultaneously used (played). This prevents us from allocating too many sounds, which would be bad for speed (not to mention that it may be impossible under some backends, like OpenAL on Windows). When all MaxAllocatedSources sources are playing, the only way to play another sound is to use appropriately high Priority to AllocateSound.

Public property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;
 
Public property InternalAllocatedSources: TInternalSoundSourceList read FAllocatedSources;

All allocated (not necessarily used) sources. Accessing this is useful only for debugging tasks, in normal circumstances this is internal. This is Nil when ContextOpen was not yet called.

Generated by PasDoc 0.16.0.