Castle Game EngineIntroduction Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers
|
Class TSoundAllocator
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 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
Overview
Fields
Methods
Properties
Description
Fields
 |
internal const DefaultMinAllocatedSources = 4; |
|
 |
internal const DefaultMaxAllocatedSources = 16; |
|
Methods
 |
constructor Create; |
|
 |
destructor Destroy; override; |
|
 |
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.
|
 |
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 |
 |
procedure StopAllSources; |
Stop all the sources currently playing. Especially useful since you have to stop a source before releasing it's associated buffer.
|
 |
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.
|
Properties
 |
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.
|
 |
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.
|
Generated by PasDoc 0.15.0.
|