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 is not only in OpenAL, it may also stem from sound hardware limitations, or limitations of APIs underneath OpenAL. 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 internal const DefaultMinAllocatedSources = 4;
Public internal const DefaultMaxAllocatedSources = 16;

Methods

Public constructor Create;
Public destructor Destroy; override;
Public function ALVersionAtLeast(const AMajor, AMinor: Integer): boolean; virtual; abstract;
Public function AllocateSound(const Importance: Integer): TSound;
Public procedure Refresh; deprecated 'do not call this method yourself, it will be called directly if you use CastleWindow unit (with TCastleApplication, TCastleWindow) or TCastleControl; 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 internal const DefaultMinAllocatedSources = 4;
 
Public internal const DefaultMaxAllocatedSources = 16;
 

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public function ALVersionAtLeast(const AMajor, AMinor: Integer): boolean; virtual; abstract;

Is the OpenAL version at least AMajor.AMinor. Available only when OpenAL is initialized, that is: between TSoundEngine.ALContextOpen and TSoundEngine.ALContextClose, only when TSoundEngine.ALActive.

Public function AllocateSound(const Importance: Integer): TSound;

Internal: Allocate sound for playing. You should initialize the OpenAL sound properties and start playing the sound (you have OpenAL sound identifier in TSound.ALSource).

Note that if you don't call alSourcePlay, the source may be detected as unused (and recycled for another sound) at the next AllocateSound, PlaySound, DetectUnusedSounds and such calls.

If we can't allocate new OpenAL sound, we return nil. This may happen your OpenAL context is not initialized. It may also happen if we cannot create more sources (because we hit MaxAllocatedSources limit, or 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 'do not call this method yourself, it will be called directly if you use CastleWindow unit (with TCastleApplication, TCastleWindow) or TCastleControl; in other cases, you shoud call ApplicationProperties._Update yourself';

Warning: this symbol is deprecated: do not call this method yourself, it will be called directly if you use CastleWindow unit (with TCastleApplication, TCastleWindow) or TCastleControl; 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) OpenAL sources. Accessing this is useful only for debugging tasks, in normal circumstances this is internal. This is Nil when ALContextOpen was not yet called.

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

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

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

At most MaxAllocatedSources sources may be simultaneously used (played). This prevents us from allocating too many sounds, which would be bad for OpenAL speed (not to mention that it may be impossible under some OpenAL implementations, like Windows one). 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.