Castle Game Engine

Class TSound

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TSound = class(TObject)

Description

Sound source that can be immediately played.

Hierarchy

Overview

Methods

Public constructor Create(const SoundEngineBackend: TSoundEngineBackend);
Public destructor Destroy; override;
Public procedure Release; virtual;
Public function PlayingOrPaused: boolean;
Public procedure KeepPlaying;

Properties

Public property Used: boolean read FUsed default false;
Public property Importance: Integer read FImportance default 0;
Public property UserData: TObject read FUserData write FUserData;
Public property OnRelease: TSoundEvent read FOnRelease write FOnRelease;
Public property Position: TVector3 read FPosition write SetPosition;
Public property Velocity: TVector3 read FVelocity write SetVelocity;
Public property Looping: boolean read FLooping write SetLooping;
Public property Relative: boolean read FRelative write SetRelative;
Public property Gain: Single read FGain write SetGain;
Public property MinGain: Single read FMinGain write SetMinGain;
Public property MaxGain: Single read FMaxGain write SetMaxGain;
Public property Buffer: TSoundBuffer read FBuffer write SetBuffer;
Public property Pitch: Single read FPitch write SetPitch;
Public property RolloffFactor: Single read FRolloffFactor write SetRolloffFactor;
Public property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance;
Public property MaxDistance: Single read FMaxDistance write SetMaxDistance;
Public property Offset: Single read GetOffset write SetOffset;

Description

Methods

Public constructor Create(const SoundEngineBackend: TSoundEngineBackend);

Create sound. This allocates sound source using the sound backend (like OpenAL source).

Exceptions raised
ENoMoreSources
If no more sources available. It should be caught and silenced by TSoundAllocator.AllocateSound.
Public destructor Destroy; override;
 
Public procedure Release; virtual;

Stops playing the source, sets Used to False, and calls OnRelease (if assigned).

You can call this if you want to stop playing the sound. This will also immediately set Used property to False and will call OnRelease.

You can call this only when Used = True.

Public 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.

Public 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

Public property Used: boolean read FUsed default false;

Do we play something. Sources that are not Used are still allocated on the sound backend (like OpenAL), and will be used when we will need them.

Public 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).

Public 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.

Public property OnRelease: TSoundEvent read FOnRelease write FOnRelease;

Called when this sound will no longer be used. This may happen because it simply finished playing, or when there are more demanding sounds (see Importance and to keep MaxAllocatedSources) and we must use this sound source for something else.

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).

Public property Position: TVector3 read FPosition write SetPosition;
 
Public property Velocity: TVector3 read FVelocity write SetVelocity;
 
Public property Looping: boolean read FLooping write SetLooping;
 
Public property Relative: boolean read FRelative write SetRelative;
 
Public property Gain: Single read FGain write SetGain;
 
Public property MinGain: Single read FMinGain write SetMinGain;
 
Public property MaxGain: Single read FMaxGain write SetMaxGain;
 
Public property Buffer: TSoundBuffer read FBuffer write SetBuffer;
 
Public property Pitch: Single read FPitch write SetPitch;
 
Public property RolloffFactor: Single read FRolloffFactor write SetRolloffFactor;
 
Public property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance;
 
Public property MaxDistance: Single read FMaxDistance write SetMaxDistance;
 
Public 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.16.0.