Castle Game EngineIntroduction Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers
|
Class TSound
Unit
CastleSoundEngine
Declaration
type TSound = class(TObject)
Description
Sound. Internally, this corresponds to an allocated OpenAL sound source.
Hierarchy
Overview
Methods
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: TVector3 read FPosition write SetPosition; |
 |
property Velocity: TVector3 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; |
 |
property Offset: Single read GetOffset write SetOffset; |
Description
Methods
 |
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.
|
 |
procedure KeepPlaying; |
Make sure that the sound keeps playing, in case it stopped playing.
This is an alternative approach to play a sound many times, like in a loop, but without using the Looping property. The idea is that you leave Looping set to False , and you keep calling this method from some "update" event (like some TInputListener.Update implementation). Once you stop calling this method, the sound will automatically stop (once it finishes the current cycle).
Note that you still (as always when using TSound) must observe the TSound.OnRelease. When it's called, it means that the sound engine (TSoundEngine) decided that this sound should be used for other purposes (there's also a very small chance that the sound engine "caught" the sound as unused, in a short time when it stopped playing but you didn't yet call this method). In such case, you must stop doing anything with this TSound instance (including calling this method, KeepPlaying , on it). You have to start playing the sound again by TSoundEngine.PlaySound instead.
Note that calling this method is better than observing TSound.OnRelease, to start playing a new sound when the previous one stopped. That's because TSound.OnRelease may be called with some small delay after the sound actually stopped, and it may be noticeable (e.g. in case of using this for a short rhytmic sound, like footsteps).
|
Properties
 |
property ALSource: TALuint read FALSource; |
Internal: OpenAL sound identifier.
|
 |
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 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.
When this event occurs, you should forget (e.g. set to Nil ) all your references to this sound instance. That's because this TSound instance may be freed (or reused for other sounds) after calling OnRelease . For the same reason, right after calling this event, 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 .
Note that we do not guarantee that sources that stopped playing will be immediately reported to OnRelease . A source may have Used = True state for a short time when it stopped playing (when PlayingOrPaused is already False ).
|
 |
property Position: TVector3 read FPosition write SetPosition; |
|
 |
property Velocity: TVector3 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 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; |
|
 |
property Offset: Single read GetOffset write SetOffset; |
Playback time of this sound, expressed in seconds.
This value will loop back to zero for looping sound sources. Setting this to something larger than the sound buffer duration is ignored.
This offset refers to the sound like it had a Pitch equal 1.0 (when the sound is not slowed down or sped up). So this offset will vary from 0 to the sound buffer duration, regardless of the current Pitch value. The actual seconds passed since the sound started playing may be different, if you will change the Pitch to something else than 1.0.
Setting this on a not-yet playing sound source (this is done by TSoundEngine.PlaySound) causes the sound to start playing from that offset.
|
Generated by PasDoc 0.15.0.
|