Class TSoundEngine
Unit
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
- TObject
- TSoundAllocator
- TSoundEngine
Overview
Fields
![]() |
nested const DefaultVolume = 1.0; |
![]() |
nested const DefaultDistanceModel = dmInverse; |
![]() |
nested const DefaultDevice = ''; |
![]() |
nested const DefaultEnabled = true; |
![]() |
class var LogVerbose: Boolean; |
Methods
![]() |
constructor Create; |
![]() |
destructor Destroy; override; |
![]() |
procedure ContextOpen; |
![]() |
procedure ContextClose; |
![]() |
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)'; |
![]() |
function LoadBuffer(const Url: String; const ExceptionOnError: Boolean = true): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)'; |
![]() |
function LoadBuffer(const Url: String; out Duration: TFloatTime): TInternalSoundBuffer; overload; deprecated 'use TCastleSound to load sound buffers (just assign TCastleSound.Url)'; |
![]() |
procedure FreeBuffer(var Buffer: TInternalSoundBuffer); deprecated 'use TCastleSound to load and free sound buffers (just assign TCastleSound.Url)'; |
![]() |
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'; |
![]() |
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'; |
![]() |
function PlaySound(const Parameters: TPlaySoundParameters): TInternalSoundSource; overload; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds'; |
![]() |
function Sound(const SoundType: TCastleSound; const Loop: boolean = false): TInternalSoundSource; deprecated 'use TCastleSound with TCastleSoundSource or SoundEngine.Play to play sounds'; |
![]() |
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'; |
![]() |
procedure Play(const ASound: TCastleSound); overload; |
![]() |
procedure Play(const PlayingSound: TCastlePlayingSound); overload; |
![]() |
procedure ParseParameters; |
![]() |
function ParseParametersHelp: string; |
![]() |
function Devices: TSoundDeviceList; |
![]() |
function DeviceCaption: string; |
Properties
![]() |
property InternalBackend: TSoundEngineBackend read Backend write SetInternalBackend; |
![]() |
property IsContextOpenSuccess: boolean read FIsContextOpenSuccess; |
![]() |
property IsContextOpen: boolean read FIsContextOpen; |
![]() |
property Information: string read FInformation; |
![]() |
property InformationSummary: string read FInformationSummary; |
![]() |
property OnOpenClose: TNotifyEventList read FOnOpenClose; |
![]() |
class property LogSoundLoading: Boolean
read GetLogSoundLoading write SetLogSoundLoading; |
![]() |
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'; |
![]() |
property Volume: Single read FVolume write SetVolume
default DefaultVolume; |
![]() |
property Device: string read FDevice write SetDevice; |
![]() |
property Enabled: boolean read FEnabled write SetEnabled default DefaultEnabled; |
![]() |
property Enable: boolean read FEnabled write SetEnabled default DefaultEnabled; deprecated 'Use Enabled'; |
![]() |
property DistanceModel: TSoundDistanceModel
read FDistanceModel write SetDistanceModel default DefaultDistanceModel; |
![]() |
property DopplerFactor: Single read FDopplerFactor write SetDopplerFactor default 0.0; |
![]() |
property DefaultRolloffFactor: Single read FDefaultRolloffFactor write FDefaultRolloffFactor; deprecated 'does nothing now; use SoundEngine.DistanceModel, TCastleSound.ReferenceDistance, TCastleSound.MaxDistance to control sound rolloff (spatialization)'; |
![]() |
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
![]() |
nested const DefaultVolume = 1.0; |
This item has no description. |
![]() |
nested const DefaultDistanceModel = dmInverse; |
This item has no description. |
![]() |
nested const DefaultDevice = ''; |
This item has no description. |
![]() |
nested const DefaultEnabled = true; |
This item has no description. |
![]() |
class var LogVerbose: Boolean; |
This item has no description. |
Methods
![]() |
constructor Create; |
This item has no description. |
![]() |
destructor Destroy; override; |
This item has no description. |
![]() |
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. |
![]() |
procedure ContextClose; |
Close the sound backend, releasing all sound resources and stopping playback. This sets IsContextOpen and IsContextOpenSuccess to You don't usually need to call this – everything will be released automatically when the sound engine is destroyed (at program finalization). |
![]() |
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
Exceptions raised
|
![]() |
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. |
![]() |
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 Exceptions raised
|
![]() |
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. |
![]() |
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. |
![]() |
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. |
![]() |
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. |
![]() |
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 Note: Instead of this method, use 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. |
![]() |
procedure Play(const PlayingSound: TCastlePlayingSound); overload; |
Play given sound. Set TCastlePlayingSound.Sound before passing it to this method. Otherwise, if TCastlePlayingSound.Sound is left 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. |
![]() |
procedure ParseParameters; |
Parse parameters in Parameters and interpret and remove recognized options. Internally it uses Parameters.Parse with ParseOnlyKnownLongOptions =
More user-oriented documentation for the above options is here: [https://castle-engine.io/openal_notes.php#section_options] |
![]() |
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. |
![]() |
function Devices: TSoundDeviceList; |
List of available sound devices. Read-only. Use 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. |
![]() |
function DeviceCaption: string; |
This item has no description. |
Properties
![]() |
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. |
![]() |
property IsContextOpenSuccess: boolean read FIsContextOpenSuccess; |
Do we have active sound rendering context. This is 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. |
![]() |
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. |
![]() |
property Information: string read FInformation; |
Multiline |
![]() |
property InformationSummary: string read FInformationSummary; |
One-line information about the currently initialized sound backend (OpenAL, FMOD etc.). |
![]() |
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). |
![]() |
class property LogSoundLoading: Boolean
read GetLogSoundLoading write SetLogSoundLoading; |
This item has no description. |
![]() |
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. |
![]() |
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. |
![]() |
property Enabled: boolean read FEnabled write SetEnabled default DefaultEnabled; |
Enable sound. Value If this is Setting this to Note that when sound backend is not initialized, sounds are not tracked, and non-looping sounds are just discarded. So toggling this property between |
![]() |
property Enable: boolean read FEnabled write SetEnabled default DefaultEnabled; deprecated 'Use Enabled'; |
Warning: this symbol is deprecated: Use Enabled This item has no description. |
![]() |
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. |
![]() |
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. |
Generated by PasDoc 0.16.0-snapshot.