Castle Game Engine: CastleSoundAllocator: Class TSound

# Class TSound
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleSoundAllocator ## Declaration `type TSound = class(TObject)` ## Description Sound (an allocated OpenAL sound source). ## Hierarchy TObject TSound ## Overview ### Methods
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure Release; virtual;`
| `function PlayingOrPaused: boolean;`
### Properties
| `property ALSource: TALuint read FALSource;`
| `property Used: boolean read FUsed default false;`
| `property Importance: Integer read FImportance default 0;`
| `property UserData: TObject read FUserData write FUserData;`
| `property OnRelease: TSoundEvent read FOnRelease write FOnRelease;`
| `property Position: TVector3Single read FPosition write SetPosition;`
| `property Velocity: TVector3Single read FVelocity write SetVelocity;`
| `property Looping: boolean read FLooping write SetLooping;`
| `property Relative: boolean read FRelative write SetRelative;`
| `property Gain: Single read FGain write SetGain;`
| `property MinGain: Single read FMinGain write SetMinGain;`
| `property MaxGain: Single read FMaxGain write SetMaxGain;`
| `property Buffer: TSoundBuffer read FBuffer write SetBuffer;`
| `property Pitch: Single read FPitch write SetPitch;`
| `property RolloffFactor: Single read FRolloffFactor write SetRolloffFactor;`
| `property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance;`
| `property MaxDistance: Single read FMaxDistance write SetMaxDistance;`
## Description ### Methods
| `constructor Create;`
Create sound. This allocates actual OpenAL source. ###### Exceptions raised ENoMoreOpenALSources If no more sources available. It should be caught and silenced by TSoundAllocator.AllocateSound.
| `destructor Destroy; override;`
| `procedure Release; virtual;`
Stops playing the source, sets Used to `False`, and calls OnRelease (if assigned). You can call this yourself if you want to stop playing the sound. It's preferable to call this (instead of manually calling alSourceStop), because this will immediately mark Used property as `False` and will call OnRelease. Otherwise we would have to get source state at some time (they are checked in AllocateSound) and check it, then see that it's no longer playing. You can call this only when Used = `True`.
| `function PlayingOrPaused: boolean;`
Is the sound playing or paused. This is almost always `True` for sounds returned by TSoundAllocator.AllocateSound, when it stops being `True` — the sound engine will realize it (soon), which will cause Release and OnRelease being automatically called, and this TSound may then be reused for playing other sounds.
### Properties
| `property ALSource: TALuint read FALSource;`
| `property Used: boolean read FUsed default false;`
Do we play something. Sources that are not Used are simply OpenAL allocated sources that are not used right now, and will be used when we will need them.
| `property Importance: Integer read FImportance default 0;`
The priority of keeping this source, relevant only when Used. Higher `Importance` means that it's more important to keep it. (I didn't name this property "Priority" so that it's obvious that higher `Importance` means more important sound).
| `property UserData: TObject read FUserData write FUserData;`
Any data comfortable to keep here by the caller of TSoundAllocator.AllocateSound. It should be initialized after calling TSoundAllocator.AllocateSound, and should be finalized in OnRelease.
| `property OnRelease: TSoundEvent read FOnRelease write FOnRelease;`
Called when this OpenAL allocated sound will no longer be used. It may stop be used because there are more demanding sources (see Importance and to keep MaxAllocatedSources) and we must assign this OpenAL sound slot to something else, or it may stop be used because it simply stopped playing. But note that we do not make any guarantees that sources that stopped playing will be immediately reported to `OnRelease`. In fact, a source may be considered in Used = `True` state for a long time until it stopped playing. That's not a problem for this unit — TSoundAllocator.AllocateSound is smart, and it may actually check (and eventually mark with Release) whether some sources are in playing state, to avoid allocating unnecessary sources. However, if this is a problem for you (because e.g. you do some expensive operations to update all used sources every time) and you really desire `OnRelease` to be called quickly after sound stoppped playing, you may call TSoundAllocator.Refresh from time to time. In this event you should make sure to delete all references to this sound, because the TSound instance may be freed (or reused for other means) after calling `OnRelease`. For the same reason, after calling this, we always clear it (set `OnRelease` to `Nil`). It's guaranteed that when this will be called, Used will be `False` and PlayingOrPaused will be `False`.
| `property Position: TVector3Single read FPosition write SetPosition;`
| `property Velocity: TVector3Single read FVelocity write SetVelocity;`
| `property Looping: boolean read FLooping write SetLooping;`
| `property Relative: boolean read FRelative write SetRelative;`
| `property Gain: Single read FGain write SetGain;`
| `property MinGain: Single read FMinGain write SetMinGain;`
| `property MaxGain: Single read FMaxGain write SetMaxGain;`
| `property Buffer: TSoundBuffer read FBuffer write SetBuffer;`
| `property Pitch: Single read FPitch write SetPitch;`
| `property RolloffFactor: Single read FRolloffFactor write SetRolloffFactor;`
| `property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance;`
| `property MaxDistance: Single read FMaxDistance write SetMaxDistance;`
Generated by PasDoc 0.13.0 on 2013-08-17 21:27:14