Class TSoundAllocator

Unit

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 (by AllocateSound method) the next unused sound source (or Nil). It can prioritize sound sources, it can reuse sound sources that finished playing, it can even 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: TSoundEngine.PlaySound, TRepoSoundEngine.Sound and TRepoSoundEngine.Sound3D.

Hierarchy

  • TObject
  • TSoundAllocator

Overview

Fields

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

Methods

Public constructor Create;
Public destructor Destroy; override;
Public function AllocateSound(const Importance: Integer): TSound;
Public procedure Refresh; deprecated 'this does not do anything now; refreshing is done automatically if you use CastleWindow unit (with TCastleApplication, TCastleWindowBase) or TCastleControlBase; in other cases, you shoud call ApplicationProperties._Update yourself';
Public procedure StopAllSources;
Public procedure LoadFromConfig(const Config: TCastleConfig); virtual;
Public procedure SaveToConfig(const Config: TCastleConfig); virtual;

Properties

Public property AllocatedSources: TSoundList read FAllocatedSources;
Published property MinAllocatedSources: Cardinal read FMinAllocatedSources write SetMinAllocatedSources default DefaultMinAllocatedSources;
Published property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;

Description

Fields

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

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public function AllocateSound(const Importance: Integer): TSound;

Internal: Allocate sound for playing. You should initialize the sound source properties and start playing the sound.

Note that if you don't call TSound.Backend.Play immediately, the source may be detected as unused (and recycled for another sound) at the next sound allocation, play, update etc.

If we can't allocate new sound source, we return nil. This may happen if your sound context is not initialized. It may also happen if we cannot create more sources (because we hit MaxAllocatedSources limit, or backend (like OpenAL) just refuses to create more sources) and all existing sounds are used and their Importance is > given here Importance.

Note for looping sounds: just like any other sound, looping sound may be stopped because the sounds are needed for other sounds. If you want to try to restart the looping sound, you will have to implement it yourself. Or you can just set Importance of looping sounds high enough, and don't use too many looping sounds, to never let them be eliminated by other sounds.

Public procedure Refresh; deprecated 'this does not do anything now; refreshing is done automatically if you use CastleWindow unit (with TCastleApplication, TCastleWindowBase) or TCastleControlBase; 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, TCastleWindowBase) or TCastleControlBase; in other cases, you shoud call ApplicationProperties._Update yourself

 
Public procedure StopAllSources;

Stop all the sources currently playing. Especially useful since you have to stop a source before releasing it's associated buffer.

Public procedure LoadFromConfig(const Config: TCastleConfig); virtual;

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.

Public procedure SaveToConfig(const Config: TCastleConfig); virtual;
 

Properties

Public property AllocatedSources: TSoundList 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.

Published 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 Importance to AllocateSound.

Published property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;
 

Generated by PasDoc 0.15.0.