Castle Game Engine

Class TCastleSound

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TCastleSound = class(TCastleComponent)

Description

Sound file 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.

This class does not handle actual playing of the sound, as it doesn't manage the 3D position of sound in case of spatial sounds, looping etc. To play it, use TCastleSoundSource. Attach TCastleSoundSource to a TCastleTransform within some TCastleViewport.

This class can be nicely serialized (so you can use this as a SubComponent e.g. in TCastleBehavior descendants that want to expose some sound, like TCastleMoveAttack).

Hierarchy

Overview

Methods

Protected procedure Loaded; override;
Protected procedure DoChange; virtual;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;

Properties

Public property Buffer: TSoundBuffer read FBuffer;
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 Spatial: Boolean read FSpatial write SetSpatial default true;
Published property MinGain: Single read FMinGain write SetMinGain default 0.0;
Published property MaxGain: Single read FMaxGain write SetMaxGain default 1.0;

Description

Methods

Protected procedure Loaded; override;
 
Protected procedure DoChange; virtual;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 

Properties

Public property Buffer: TSoundBuffer read FBuffer;

Loaded sound buffer, for playing the buffer with the SoundEngine. Nil if not loaded.

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. Changing this also changes 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 wav, ogg and such files) louder/more silent for this purpose. This is usually bad for sound quality. Instead, keep your sound data at max loudness (normalized), and use this gain property to scale sound.

It can be anything from 0 to +infinity. The default is 1. Note that values > 1 are allowed, but some sound backends (like OpenAL) may clip the resulting sound volume (after all spatial calculations are be done) to 1.0.

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

Sound playing speed.

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 it allowed.

Published property Spatial: Boolean read FSpatial write SetSpatial default true;

Is the sound playback spatialized.

Spatial sounds are louder/more silent depending on their 3D distance to listener (this means a distance from TCastleTransform origin to the camera within the TCastleViewport).

Note that some sound backends (like OpenAL) can only spatialize mono sounds, and play stereo sounds always as non-spatialized.

Published property MinGain: Single read FMinGain write SetMinGain default 0.0;

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.

Published property MaxGain: Single read FMaxGain write SetMaxGain default 1.0;

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.

Generated by PasDoc 0.16.0.