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; |
|
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 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 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 DistanceModel: TSoundDistanceModel
read FDistanceModel write SetDistanceModel default DefaultDistanceModel; |
|
property DopplerFactor: Single read FDopplerFactor write SetDopplerFactor default 0.0; |
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). |
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 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 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.