Castle Game Engine

Class TCastlePlayingSound

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TCastlePlayingSound = class(TComponent)

Description

Controls a sound playback. You can pass an instance of it to TSoundEngine.Play or TCastleSoundSource.Play. It allows to control sound playback before you start playing (like OnStop) and after (like Offset).

You can reuse the same instance of TCastlePlayingSound for playback many times, but you can start new playback only if the previous one finished. IOW, you can pass to TSoundEngine.Play or TCastleSoundSource.Play only instances when Playing is False. If you don't want to wait, just create a new instance of TCastlePlayingSound – they are designed to be lightweight, you can create them during runtime.

Destroying this class always stops the associated sound playback. Note that it is a TComponent descendant, so you can make it automatically destroyed when some owner TComponent is destroyed.

You can make your own descendants of this class, to associate any additional information with the playback of the sound.

Hierarchy

Overview

Methods

Protected procedure DoStop; virtual;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function Playing: Boolean;
Public procedure Stop;

Properties

Public property Sound: TCastleSound read FSound write SetSound;
Public property OnStop: TNotifyEvent read FOnStop write SetOnStop;
Public property FreeOnStop: Boolean read FFreeOnStop write SetFreeOnStop default false;
Public property Loop: Boolean read FLoop write SetLoop default false;
Public property Volume: Single read FVolume write SetVolume default 1.0;
Public property Pitch: Single read FPitch write SetPitch default 1.0;
Public property Offset: Single read GetOffset write SetOffset;
Public property InitialOffset: Single read FInitialOffset write FInitialOffset;

Description

Methods

Protected procedure DoStop; virtual;

Do the necessary job after source stopped, due to any reason. In this class it handles OnStop and FreeOnStop.

If you override this: Since FreeOnStop may free the instance, you should add your code before calling inherited.

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public function Playing: Boolean;

Is the sound playing now. Using TSoundEngine.Play or TCastleSoundSource.Play makes it True for some time, then (right before OnStop) it switches back to False.

Public procedure Stop;

Stop playing now. Note that you can also free the TCastlePlayingSound instance, it will always automatically stop the playback.

Calling this on a sound that is not playing is allowed, and ignored.

Properties

Public property Sound: TCastleSound read FSound write SetSound;

Associated sound used for playing. You have to set it before playing. Cannot be changed while playing.

Public property OnStop: TNotifyEvent read FOnStop write SetOnStop;

If provided, we will call this event when sound stops playing.

Note that in some cases the sound cannot be played at all. For example when TCastleSound is not loaded (no TCastleSound.URL provided, or invalid TCastleSound.URL provided) or when there are no free sound sources (these are limited in sound backends; the new sound may "steal" some sound source but only if the TCastleSound.Priority is high enough). Then TSoundEngine.Play or TCastleSoundSource.Play call the OnStop event immediately, from within Play call.

If the object owning the notification method may be destroyed before TCastlePlayingSound is destroyed, be sure to set this callback to Nil. Otherwise the callback could try calling method of a non-existent object.

You can only set this when sound is not playing (as otherwise it would be an easy source of bugs – sometimes TSoundEngine.Play wants to immediately stop sound playback).

Public property FreeOnStop: Boolean read FFreeOnStop write SetFreeOnStop default false;

Automatically free when the playback finishes. If the playback is not yet started, it will wait for it to start, and then finish.

You can only set this when sound is not playing (as otherwise it would be an easy source of bugs – sometimes TSoundEngine.Play wants to immediately stop sound playback).

Public property Loop: Boolean read FLoop write SetLoop default false;

Is the playback looping. You can change this on a playing or stopped sound.

Public property Volume: Single read FVolume write SetVolume default 1.0;

Volume (how loud the playing sound is).

The effective sound volume is a multiplication of TCastleSound.Volume, TCastlePlayingSound.Volume and TCastleSoundSource.Volume (if the sound is played through TCastleSoundSource). It is also affected by spatial calculations (if the sound is played through TCastleSoundSource with TCastleSoundSource.Spatial = True) and finally by a master SoundEngine.Volume.

Any value > 0 is allowed.

Public property Pitch: Single read FPitch write SetPitch default 1.0;

Sound playing speed.

The effective sound pitch is a multiplication of TCastleSound.Pitch, TCastlePlayingSound.Pitch and TCastleSoundSource.Pitch (if the sound is played through TCastleSoundSource).

Any value > 0 is allowed.

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 duration (which you can read from TCastleSound.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 TCastleSound.Duration, regardless of the initial/current TCastleSound.Pitch value. The actual seconds passed since the sound started playing may be different, if you change the TCastleSound.Pitch to something else than 1.0.

Using this on a sound that is not playing is allowed. Getting this value always returns zero in this case, and setting it is ignored.

Note: you can adjust InitialOffset to determine the offset for starting new sound. It is deliberately a separate property from current Offset, otherwise it would be too easy to accidentally start playing in the middle when you wanted to play from the start.

Public property InitialOffset: Single read FInitialOffset write FInitialOffset;

Initial position, in seconds, within the sound when we start playing it. You can get/set this property regardless of whether sound is playing.

Generated by PasDoc 0.16.0.