Castle Game Engine: CastleSoundAllocator: Class TSoundAllocator

# Class TSoundAllocator
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleSoundAllocator ## Declaration `type TSoundAllocator = class(TObject)` ## Description Manage allocated OpenAL sounds. You leave to this class creating and deleting of OpenAL sounds. When you need OpenAL sound to do something, just call AllocateSound method. This class will manage OpenAL sources in an intelligent manner, which means when you need new sound, we may Reuse already allocated sound that is not used to play anything. Allocate new sound (but we will keep allocated sounds count within MaxAllocatedSources sound limit, to not overload OpenAL implementation with work). We may simply interrupt already allocated sound, if new sound is more important. Our OpenAL resources are created in ALContextOpen, and released in ALContextClose. The very reason behind this class is to hide from you the fact that the number of OpenAL sources are limited. In particular, this means that when OpenAL will run out of sources, no OpenAL error (alGetError) will be left, and no exception will be raised. In the worst case TSoundAllocator.AllocateSound will return nil, but in more probable cases some other sources (unused, or with less priority) will be reused. Note that this means that the code in this unit must read in some situations alGetError. That's because reading alGetError is the only way to know when OpenAL implementation has run out of sources. So the code in this unit may in various places raise EALError if you made some error in your OpenAL code, and you didn't check alGetError yourself often enough. ## Hierarchy TObject TSoundAllocator ## Overview ### Fields
| `internal const DefaultMinAllocatedSources = 4;`
| `internal const DefaultMaxAllocatedSources = 16;`
### Methods
| `procedure LoadFromConfig(const Config: TCastleConfig); virtual;`
| `procedure SaveToConfig(const Config: TCastleConfig); virtual;`
| `constructor Create;`
| `procedure ALContextOpen; virtual;`
| `procedure ALContextClose; virtual;`
| `function AllocateSound(const Importance: Integer): TSound;`
| `procedure Refresh;`
| `procedure StopAllSources;`
### Properties
| `property AllocatedSources: TSoundList read FAllocatedSources;`
| `property MinAllocatedSources: Cardinal read FMinAllocatedSources write SetMinAllocatedSources default DefaultMinAllocatedSources;`
| `property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;`
## Description ### Fields
| `internal const DefaultMinAllocatedSources = 4;`
| `internal const DefaultMaxAllocatedSources = 16;`
### Methods
| `procedure LoadFromConfig(const Config: TCastleConfig); virtual;`
Load and save into XML config file some sound engine properties. 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.
| `procedure SaveToConfig(const Config: TCastleConfig); virtual;`
| `constructor Create;`
| `procedure ALContextOpen; virtual;`
| `procedure ALContextClose; virtual;`
| `function AllocateSound(const Importance: Integer): TSound;`
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, Refresh 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;`
Detect unused sound sources. If you rely on your sources receiving TSound.OnRelease in a timely manner, be sure to call this method often. Otherwise, it's not needed to call this at all (unused sounds will be detected automatically on-demand anyway). This is automatically called by TCastleSceneManager. For every source that is marked as Used, this checks whether this source is actually in playing/paused state right now. If not, it calls TSound.Release (thus setting Used to `False` and triggering OnRelease) for this source.
| `procedure StopAllSources;`
Stop all the sources currently playing. Especially useful since you have to stop a source before releasing it's associated buffer.
### Properties
| `property AllocatedSources: TSoundList read FAllocatedSources;`
All allocated (not necessarily used) OpenAL sources. Useful only for advanced or debuging tasks, in normal circumstances we mange this completely ourselves. 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.
| `property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;`
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:12