Castle Game Engine

Class TCastleSound

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TCastleSound = class(TCastleComponent)

Description

Sound that can be loaded from URL (possibly reusing a cache, possibly using streaming) and played.

Aside from sound file (also called "sound buffer" or "audio clip" in various APIs) this class allows to configue also playback values, like Volume and Pitch. These playback values are intended to reflect preferences specific to this sound file. They are multiplied by playback values of the TCastleSoundSource (TCastleSoundSource.Volume, TCastleSoundSource.Pitch) and TCastlePlayingSound (to adjust it per-playback, using TCastlePlayingSound.Volume, TCastlePlayingSound.Pitch).

This class does not actually play the sound. It only defines something that can be played. To play the sound use SoundEngine.Play or TCastleSoundSource. For spatial sounds, attach TCastleSoundSource to a TCastleTransform within some TCastleViewport and set TCastleSoundSource.Sound or call TCastleSoundSource.Play.

Hierarchy

Overview

Fields

Public nested const DefaultReferenceDistance = 1.0;
Public nested const DefaultMaxDistance = 10000.0;

Methods

Protected procedure Loaded; override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public function Duration: Single;
Public function DataFormat: TSoundDataFormat;
Public function Frequency: LongWord;

Properties

Public property MinGain: Single read FMinGain write SetMinGain default 0.0; platform;
Public property MaxGain: Single read FMaxGain write SetMaxGain default 1.0; platform;
Published property URL: String read FURL write SetURL;
Published property Stream: Boolean read FStream write SetStream default false;
Published property Volume: Single read FVolume write SetVolume default 1.0;
Published property Pitch: Single read FPitch write SetPitch default 1.0;
Published property Priority: Single read FPriority write SetPriority default 0.5;
Published property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance default DefaultReferenceDistance;
Published property MaxDistance: Single read FMaxDistance write SetMaxDistance default DefaultMaxDistance;

Description

Fields

Public nested const DefaultReferenceDistance = 1.0;
 
Public nested const DefaultMaxDistance = 10000.0;
 

Methods

Protected procedure Loaded; override;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public function PropertySections(const PropertyName: String): TPropertySections; override;
 
Public function Duration: Single;

Duration of the sound, in seconds. -1 if not loaded yet. The sound is loaded once you set URL and don't get any loading exceptions.

Public function DataFormat: TSoundDataFormat;

Sound data format (disregarding compression on top of it), for informational purposes. Undefined if not loaded yet. The sound is loaded once you set URL and don't get any loading exceptions.

Public function Frequency: LongWord;

Frequency (sample rate) of the loaded sound file. 0 if not loaded yet. The sound is loaded once you set URL and don't get any loading exceptions.

Properties

Public property MinGain: Single read FMinGain write SetMinGain default 0.0; platform;

Warning: this symbol is specific to some platform.

Force a minimum sound loudness, despite what volume would be calculated by the spatialization. This can be used to force sound to be audible, even when it's far away from the listener.

It must be in [0, 1] range. By default it is 0.

Public property MaxGain: Single read FMaxGain write SetMaxGain default 1.0; platform;

Warning: this symbol is specific to some platform.

Force a maximum sound loudness, despite what volume would be calculated by the spatialization. This can be used to limit sound volume, regardless of the distance attenuation calculation.

It must be in [0, 1] range. By default it is 1.

Published property URL: String read FURL write SetURL;

URL of the sound file. Set this to load a new sound buffer, you can set to '' to clear the sound buffer.

If you plan to change Stream, note that it is best to do it before setting URL. Changing Stream while URL is already set means that the sound is reloaded.

Published property Stream: Boolean read FStream write SetStream default false;

Play sound using streaming. This means that the sound is gradually decompressed in memory, which means that loading time is much smaller, although there may be a small overhead on CPU during playback. Streaming is usually a good idea for longer sounds, e.g. music tracks.

See also TSoundLoading for details.

If you plan to change Stream, note that it is best to do it before setting URL. Changing Stream while URL is already set means that the sound is reloaded.

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

Volume (how loud the sound is).

Use this to indicate that e.g. a plane engine is louder than a mouse squeak (when heard from the same distance). Note: Do not make the actual sound data (in sound files) louder/more silent to express that something is louder/more silent in reality. This would usually lower the sound quality. Instead, keep your sound file data at max loudness ("normalized"), and use this property to adjust the volume associated with the sound.

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. The default is 1. Note that, while values > 1 are allowed, but some sound backends (like OpenAL) may clip the resulting sound volume (after all volume influences, including spatial calculations are done) to 1.0.

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

Changing this naturally also changes the audible sound. Each reduction by 50 percent equals a pitchshift of -12 semitones (one octave reduction). Each doubling equals a pitch shift of 12 semitones (one octave increase).

Any value > 0 is allowed.

Published property Priority: Single read FPriority write SetPriority default 0.5;

How important is the sound, between 0.0 (least important) to 1.0 (most important).

The sound engine sometimes has to interrupt (or even not start at all) playback of some non-important sound, to have a good performance of audio mixing. In these cases, the sound with higher priority always "wins" over sound with lower priority. That is, sound with lower priority will be interrupted (the slot will be "stolen") to make room for sound with higher priority.

Note: Many sound APIs (Unity, FMOD, Wwise, X3D...) have a similar property, with inconsistent range (minimum, maximum) and inconsistent meaning (some say "lower is more important", some say "higher is more important"). Our treatment of this property is similar to X3D, as it satisfies a number of important points: it defines easy to remember min/max (0 and 1), it is agnostic to the underlying precision (e.g. it has to map to 257 levels in FMOD, 100 levels in Wwise). Also, "higher is more important" seems just more natural.

Published property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance default DefaultReferenceDistance;

Spatial sound is fully audible (with Volume) at this distance. See TSoundDistanceModel for a description how distance affects the sound volume.

Published property MaxDistance: Single read FMaxDistance write SetMaxDistance default DefaultMaxDistance;

Distance at which sound volume stops attenuating. For the linear distance model (SoundEngine.DistanceModel = dmLinear) this is also a distance at which sound volume drops to zero (completely silent). See TSoundDistanceModel for a description how distance affects the sound volume.

Generated by PasDoc 0.16.0.