API Reference

Class TSoundEngine

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TSoundEngine = class(TSoundAllocator)

Description

Sound engine, responsible for loading and playing sounds. See manual about sound in Castle Game Engine for an overview of sound support.

There should always be only one instance of this class, accessed through the global SoundEngine routine.

Hierarchy

Overview

Fields

Public nested const DefaultVolume = 1.0;
Public nested const DefaultDistanceModel = dmInverse;
Public nested const DefaultDevice = '';
Public nested const DefaultEnabled = true;
Public class var LogVerbose: Boolean;

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure ContextOpen;
Public procedure ContextClose;
Public function LoadBuffer(const Url: String; const SoundLoading: TSoundLoading; const ExceptionOnError: Boolean = true): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)';
Public function LoadBuffer(const Url: String; const ExceptionOnError: Boolean = true): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)';
Public function LoadBuffer(const Url: String; out Duration: TFloatTime): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)';
Public procedure FreeBuffer(var Buffer: TInternalSoundBuffer); deprecated 'use TCastleSound to load and free sound buffers (just assign TCastleSound.Url)';
Public function PlaySound(const Buffer: TInternalSoundBuffer; const Spatial, Loop: boolean; const Priority: Single; const Volume, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single = 1): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';
Public function PlaySound(const Buffer: TInternalSoundBuffer; const Spatial, Loop: boolean; const Priority: Single; const Volume, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single; const ReferenceDistance: Single; const MaxDistance: Single): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';
Public function PlaySound(const Parameters: TPlaySoundParameters): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';
Public function Sound(const SoundType: TCastleSound; const Loop: boolean = false): TInternalSoundSource; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';
Public function Sound3D(const SoundType: TCastleSound; const Position: TVector3; const Loop: boolean = false): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';
Public procedure Play(const ASound: TCastleSound); overload;
Public procedure Play(const PlayingSound: TCastlePlayingSound); overload;
Public procedure ParseParameters;
Public function ParseParametersHelp: string;
Public function Devices: TSoundDeviceList;
Public function DeviceCaption: string;

Properties

Public property InternalBackend: TSoundEngineBackend read Backend write SetInternalBackend;
Public property IsContextOpenSuccess: boolean read FIsContextOpenSuccess;
Public property IsContextOpen: boolean read FIsContextOpen;
Public property Information: string read FInformation;
Public property InformationSummary: string read FInformationSummary;
Public property OnOpenClose: TNotifyEventList read FOnOpenClose;
Public class property LogSoundLoading: Boolean read GetLogSoundLoading write SetLogSoundLoading;
Public property InitialPitchMultiplier: Single read FInitialPitchMultiplier write FInitialPitchMultiplier default 1.0; deprecated 'use TCastlePlayingSound and set TCastlePlayingSound.Pitch before playing, to influence initial pitch; this property is not reliable when combined with TCastlePlayingSound.Pitch usage';
Public property Volume: Single read FVolume write SetVolume default DefaultVolume;
Public property Device: string read FDevice write SetDevice;
Public property Enabled: boolean read FEnabled write SetEnabled default DefaultEnabled;
Public property Enable: boolean read FEnabled write SetEnabled default DefaultEnabled; deprecated 'Use Enabled';
Public property DistanceModel: TSoundDistanceModel read FDistanceModel write SetDistanceModel default DefaultDistanceModel;
Public property DopplerFactor: Single read FDopplerFactor write SetDopplerFactor default 0.0;
Public property DefaultRolloffFactor: Single read FDefaultRolloffFactor write FDefaultRolloffFactor; deprecated 'does nothing now; use SoundEngine.DistanceModel, TCastleSound.ReferenceDistance, TCastleSound.MaxDistance to control sound rolloff (spatialization)';
Public property DefaultReferenceDistance: Single read FDefaultReferenceDistance write FDefaultReferenceDistance; deprecated 'does nothing now; use SoundEngine.DistanceModel, TCastleSound.ReferenceDistance, TCastleSound.MaxDistance to control sound rolloff (spatialization)';

Description

Fields

Public nested const DefaultVolume = 1.0;

This item has no description.

Public nested const DefaultDistanceModel = dmInverse;

This item has no description.

Public nested const DefaultDevice = '';

This item has no description.

Public nested const DefaultEnabled = true;

This item has no description.

Public class var LogVerbose: Boolean;

This item has no description.

Methods

Public constructor Create;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure ContextOpen;

Initialize sound backend. Sets IsContextOpen, IsContextOpenSuccess, Information.

You don't usually need to call this – everything will be initialized automatically when you first load a sound (or try to load and play it).

You can set Device before calling this.

Note that we continue (without any exception) if the initialization failed for any reason (e.g. OpenAL library is not available, or no sound output device is available). You can check IsContextOpenSuccess and Information to know if the initialization was actually successful. But you can also ignore it, the sound engine will silently (literally) keep working even if OpenAL could not be initialized.

Public procedure ContextClose;

Close the sound backend, releasing all sound resources and stopping playback. This sets IsContextOpen and IsContextOpenSuccess to False. It's allowed and harmless to call this when one of them is already False.

You don't usually need to call this – everything will be released automatically when the sound engine is destroyed (at program finalization).

Public function LoadBuffer(const Url: String; const SoundLoading: TSoundLoading; const ExceptionOnError: Boolean = true): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)';

Warning: this symbol is deprecated: use TCastleSound to load sound buffers (just assign TCastleSound.Url)

Load a sound file contents such that they can be immediately played.

This method tries to initialize backend (like OpenAL) context, and loads the buffer contents. But even when it fails, it still returns a valid (non-nil) TInternalSoundBuffer instance. As the OpenAL context may be lost while the game is ongoing (in case of Android) we take care to reload it when necessary.

The buffer should be released by FreeBuffer later when it's not needed. Although we will take care to always free remaining buffers before closing OpenAL context anyway.

We have a cache of sound files here. An absolute URL will be recorded as being loaded to given buffer. Loading the same URL second time returns the same buffer instance. The buffer is released only once you call FreeBuffer as many times as you called LoadBuffer for it.

Parameters
ExceptionOnError
When to raise exception, or merely make a warning by WritelnWarning, in case of error when loading.

Note that it always returns non-nil, even in case of ExceptionOnError=False and an error at loading. But in this case, TInternalSoundBuffer is mostly a useless empty instance. Do not depend on this behavior, and check for Nil result in case you use ExceptionOnError=False.

SoundLoading
Specifies whether to load sound at once, or use streaming. See TSoundLoading for details.
Exceptions raised
ESoundFileError
If loading of this sound file failed. There are many reasons why this may happen: we cannot read given URL, or it may contain invalid contents, or a library required to decompress e.g. OggVorbis is missing.
Public function LoadBuffer(const Url: String; const ExceptionOnError: Boolean = true): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)';

Warning: this symbol is deprecated: use TCastleSound to load sound buffers (just assign TCastleSound.Url)

This item has no description.

Public function LoadBuffer(const Url: String; out Duration: TFloatTime): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)';

Warning: this symbol is deprecated: use TCastleSound to load sound buffers (just assign TCastleSound.Url)

This item has no description.

Public procedure FreeBuffer(var Buffer: TInternalSoundBuffer); deprecated 'use TCastleSound to load and free sound buffers (just assign TCastleSound.Url)';

Warning: this symbol is deprecated: use TCastleSound to load and free sound buffers (just assign TCastleSound.Url)

Free a sound file buffer. Ignored when buffer is Nil. Buffer is always set to Nil after this.

Exceptions raised
ESoundBufferNotLoaded
When invalid (not Nil, and not returned by LoadBuffer) buffer identifier is given.
Public function PlaySound(const Buffer: TInternalSoundBuffer; const Spatial, Loop: boolean; const Priority: Single; const Volume, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single = 1): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';

Warning: this symbol is deprecated: use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds

This item has no description.

Public function PlaySound(const Buffer: TInternalSoundBuffer; const Spatial, Loop: boolean; const Priority: Single; const Volume, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single; const ReferenceDistance: Single; const MaxDistance: Single): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';

Warning: this symbol is deprecated: use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds

This item has no description.

Public function PlaySound(const Parameters: TPlaySoundParameters): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';

Warning: this symbol is deprecated: use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds

This item has no description.

Public function Sound(const SoundType: TCastleSound; const Loop: boolean = false): TInternalSoundSource; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';

Warning: this symbol is deprecated: use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds

Simply play given TCastleSound. This should be used to play sounds that are not spatial, i.e. have no place in 3D space.

Returns used TInternalSoundSource (or nil if none was available) to further control the sound. It is deprecated: You should not use this TInternalSoundSource instance anymore. If you need more elaborate sound control, use TCastleSoundSource to play sounds, that also automaticall applies TCastleSound changes to the playing sound.

Public function Sound3D(const SoundType: TCastleSound; const Position: TVector3; const Loop: boolean = false): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds';

Warning: this symbol is deprecated: use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds

Play given sound at appropriate position in 3D space.

Returns used TInternalSoundSource (or nil if none was available) to further control the sound. It is deprecated: You should not use this TInternalSoundSource instance anymore. If you need more elaborate sound control, use TCastleSoundSource to play sounds, that also automaticall applies TCastleSound changes to the playing sound.

Public procedure Play(const ASound: TCastleSound); overload;

Play given sound once (not looping).

This is the simplest method to just play the sound and "forget about it" (no need to manage the playback afterwards).

It is allowed to set ASound to Nil. Nothing will be played then.

Note: Instead of this method, use Play(TCastlePlayingSound) overload to have more control over the sound (before and after it starts playing).

This only plays non-spatial sounds, as it doesn't give any control over the sound 3D position. Instead of this method, use TCastleSoundSource (attached to some TCastleTransform) for spatial sounds to control their 3D position.

Public procedure Play(const PlayingSound: TCastlePlayingSound); overload;

Play given sound.

Set TCastlePlayingSound.Sound before passing it to this method. Otherwise, if TCastlePlayingSound.Sound is left Nil, nothing will be played.

Use the PlayingSound (TCastlePlayingSound) properties to provide additional information about the sound playback. E.g. assign TCastlePlayingSound.Loop TCastlePlayingSound.OnStop or control sound afterwards by TCastlePlayingSound.Stop, TCastlePlayingSound.Offset.

Consider using TCastlePlayingSound.FreeOnStop if you don't want to manage the lifetime of the TCastlePlayingSound instance.

This only plays non-spatial sounds, as it doesn't give any control over the sound 3D position. Instead of this method, use TCastleSoundSource (attached to some TCastleTransform) for spatial sounds to control their 3D position.

Public procedure ParseParameters;

Parse parameters in Parameters and interpret and remove recognized options. Internally it uses Parameters.Parse with ParseOnlyKnownLongOptions = True. Recognized options:

--audio-device DEVICE-NAME

Set Device variable to given argument.

--no-sound

Disable any sound (sets Enable to False).

More user-oriented documentation for the above options is here: [https://castle-engine.io/openal_notes.php#section_options]

Public function ParseParametersHelp: string;

Help string for options parsed by ParseParameters.

Note that it also lists the available sound output Devices, as they are valid arguments for the --audio-device option.

Public function Devices: TSoundDeviceList;

List of available sound devices. Read-only.

Use Devices[].Name as Device values.

On some backend implementations, also some other Device values may be possible. E.g. old Loki implementation of OpenAL allowed some hints to be encoded in Lisp-like language inside the Device string.

Public function DeviceCaption: string;

This item has no description.

Properties

Public property InternalBackend: TSoundEngineBackend read Backend write SetInternalBackend;

Sound backend, like OpenAL or FMOD or SOX. See OpenAL or FMOD.

Do not change or access this yourself. You can change this only by calling procedure like UseFMODSoundBackend from CastleFMODSoundBackend unit.

Public property IsContextOpenSuccess: boolean read FIsContextOpenSuccess;

Do we have active sound rendering context. This is True when you successfully called ContextOpen (and you didn't call ContextClose yet).

You should not need this property much. The whole CastleSoundEngine API works regardless if the context was successfully open or not. However, reading this is useful to display to user warning e.g. "Sound could not be initialized for some reason" (use Information to get the details).

In case of OpenAL backend, this also implies that OpenAL library is loaded.

Public property IsContextOpen: boolean read FIsContextOpen;

Did we attempt to initialize sound rendering context. This indicates that ContextOpen was called, and not closed with ContextClose yet. Contrary to IsContextOpenSuccess, this doesn't care if ContextOpen was a success.

Public property Information: string read FInformation;

Multiline information about the currently initialized sound backend (OpenAL, FMOD etc.).

Public property InformationSummary: string read FInformationSummary;

One-line information about the currently initialized sound backend (OpenAL, FMOD etc.).

Public property OnOpenClose: TNotifyEventList read FOnOpenClose;

Events fired after sound context is being open or closed. More precisely, when IsContextOpen changes (and so, possibly, IsContextOpenSuccess changed).

Public class property LogSoundLoading: Boolean read GetLogSoundLoading write SetLogSoundLoading;

This item has no description.

Public property InitialPitchMultiplier: Single read FInitialPitchMultiplier write FInitialPitchMultiplier default 1.0; deprecated 'use TCastlePlayingSound and set TCastlePlayingSound.Pitch before playing, to influence initial pitch; this property is not reliable when combined with TCastlePlayingSound.Pitch usage';

Warning: this symbol is deprecated: use TCastlePlayingSound and set TCastlePlayingSound.Pitch before playing, to influence initial pitch; this property is not reliable when combined with TCastlePlayingSound.Pitch usage

Newly played sounds will have TInternalSoundSource.Pitch multiplied by this.

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

Sound volume, affects all sounds (effects and music). Must be within 0..1 range.

Setting volume to 0.0 means that there is no sound output (this case should be optimized). The sounds played are still tracked.

Public property Device: string read FDevice write SetDevice;

Sound output device, used when initializing sound context.

You can change it even when context is already initialized. Then we'll close the old device (ContextClose), change Device value, and initialize context again (ContextOpen). Note that you will need to reload your buffers and sources again.

Public property Enabled: boolean read FEnabled write SetEnabled default DefaultEnabled;

Enable sound. Value True, the default, means that we will initialize sound backend and play all sounds as you expect.

If this is False, then we will not initialize any sound backend even if you try to load or play some sound. This is useful if you simply want to disable any sound output (or backend, like OpenAL, usage), even when sound library (like OpenAL) is available.

Setting this to False when the sound backend is already initialized will close it, stopping the playback of all existing sound sources.

Note that when sound backend is not initialized, sounds are not tracked, and non-looping sounds are just discarded. So toggling this property between False and True will simply restart all looping sounds from the beginning. So setting this to False is not a way to "pause" or "mute" sound playback, it's a way to "stop" sound playback. If you want to mute all sounds, but be able to unmute them when necessary, set the Volume to zero.

Public property Enable: boolean read FEnabled write SetEnabled default DefaultEnabled; deprecated 'Use Enabled';

Warning: this symbol is deprecated: Use Enabled

This item has no description.

Public property DistanceModel: TSoundDistanceModel read FDistanceModel write SetDistanceModel default DefaultDistanceModel;

How does the distance affect spatial sounds (with TCastleSoundSource.Spatial). See TSoundDistanceModel for the description of possible options.

Public property DopplerFactor: Single read FDopplerFactor write SetDopplerFactor default 0.0;

Emphasize or deemphasize the Doppler effect. See https://en.wikipedia.org/wiki/Doppler_effect and CGE demo examples/audio/doppler_effect to see what it is.

Allowed values are anything > 0. Value 0 disables the Doppler effect. This is the default, otherwise the Doppler effect would be way too audible in 2D games. Value 1 makes a correct Doppler effect if the distance in your world of 1 unit corresponds to 1 meter. Larger values allow to emphasize the effect more.

Public property DefaultRolloffFactor: Single read FDefaultRolloffFactor write FDefaultRolloffFactor; deprecated 'does nothing now; use SoundEngine.DistanceModel, TCastleSound.ReferenceDistance, TCastleSound.MaxDistance to control sound rolloff (spatialization)';

Warning: this symbol is deprecated: does nothing now; use SoundEngine.DistanceModel, TCastleSound.ReferenceDistance, TCastleSound.MaxDistance to control sound rolloff (spatialization)

This item has no description.

Public property DefaultReferenceDistance: Single read FDefaultReferenceDistance write FDefaultReferenceDistance; deprecated 'does nothing now; use SoundEngine.DistanceModel, TCastleSound.ReferenceDistance, TCastleSound.MaxDistance to control sound rolloff (spatialization)';

Warning: this symbol is deprecated: does nothing now; use SoundEngine.DistanceModel, TCastleSound.ReferenceDistance, TCastleSound.MaxDistance to control sound rolloff (spatialization)

This item has no description.

Generated by PasDoc 0.16.0-snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.