Class TSoundEngine

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

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.

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

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.

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.

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 Enabled to False).

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

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.

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.

This item has no description.

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.

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.

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

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

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

This item has no description.

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.

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.

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.

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

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.