Public	`DefaultMinAllocatedSources = 4;`
Public	`DefaultMaxAllocatedSources = 16;`
Public	`DefaultVolume = 1.0;`
Public	`DefaultDistanceModel = dmInverse;`
Public	`DefaultDevice = '';`
Public	`DefaultEnabled = true;`

Fields

Public class var LogVerbose: Boolean;

Methods

Public	`constructor Create;`
Public	`destructor Destroy; override;`
Public	`procedure ContextOpen;`
Public	`procedure ContextClose;`
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 MinAllocatedSources: Cardinal read FMinAllocatedSources write SetMinAllocatedSources default DefaultMinAllocatedSources;`
Public	`property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;`
Public	`property InternalAllocatedSources: TInternalSoundSourceList read FAllocatedSources;`
Public	`property IsContextOpenSuccess: boolean read FIsContextOpenSuccess;`
Public	`property InternalBackend: TSoundEngineBackend read Backend write SetInternalBackend;`
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 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 DistanceModel: TSoundDistanceModel read FDistanceModel write SetDistanceModel default DefaultDistanceModel;`
Public	`property DopplerFactor: Single read FDopplerFactor write SetDopplerFactor default 0.0;`

Description

Constants

Public DefaultMinAllocatedSources = 4;

This item is declared in ancestor TSoundAllocator.

This item has no description.

Source: audio/castlesoundengine_allocator.inc (line 84).

Public DefaultMaxAllocatedSources = 16;

This item is declared in ancestor TSoundAllocator.

This item has no description.

Source: audio/castlesoundengine_allocator.inc (line 85).

Public DefaultVolume = 1.0;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 149).

Public DefaultDistanceModel = dmInverse;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 150).

Public DefaultDevice = '';

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 151).

Public DefaultEnabled = true;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 152).

Fields

Public class var LogVerbose: Boolean;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 155).

Methods

Public constructor Create;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 157).

Public destructor Destroy; override;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 158).

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.

Source: audio/castlesoundengine_engine.inc (line 175).

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

Source: audio/castlesoundengine_engine.inc (line 183).

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.

Source: audio/castlesoundengine_engine.inc (line 224).

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.

Source: audio/castlesoundengine_engine.inc (line 244).

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

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

Source: audio/castlesoundengine_engine.inc (line 264).

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.

Source: audio/castlesoundengine_engine.inc (line 270).

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.

Source: audio/castlesoundengine_engine.inc (line 282).

Public function DeviceCaption: string;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 284).

Properties

Public property MinAllocatedSources: Cardinal read FMinAllocatedSources write SetMinAllocatedSources default DefaultMinAllocatedSources;

This item is declared in ancestor TSoundAllocator.

Minimum / maximum number of allocated sources. Always keep MinAllocatedSources <= MaxAllocatedSources.

For the sake of speed, we always keep allocated at least MinAllocatedSources sources. This must be >= 1. Setting MinAllocatedSources too large value will raise ENoMoreSources.

At most MaxAllocatedSources sources may be simultaneously used (played). This prevents us from allocating too many sounds, which would be bad for speed (not to mention that it may be impossible under some backends, like OpenAL on Windows). When all MaxAllocatedSources sources are playing, the only way to play another sound is to use appropriately high Priority to AllocateSound.

Source: audio/castlesoundengine_allocator.inc (line 107).

Public property MaxAllocatedSources: Cardinal read FMaxAllocatedSources write SetMaxAllocatedSources default DefaultMaxAllocatedSources;

This item is declared in ancestor TSoundAllocator.

This item has no description.

Source: audio/castlesoundengine_allocator.inc (line 111).

Public property InternalAllocatedSources: TInternalSoundSourceList read FAllocatedSources;

This item is declared in ancestor TSoundAllocator.

All allocated (not necessarily used) sources. Accessing this is useful only for debugging tasks, in normal circumstances this is internal. This is Nil when ContextOpen was not yet called.

Source: audio/castlesoundengine_allocator.inc (line 120).

Public property IsContextOpenSuccess: boolean read FIsContextOpenSuccess;

This item is declared in ancestor TSoundAllocator.

Do we have active sound rendering context. This is True when you successfully called TSoundEngine.ContextOpen and you didn't call TSoundEngine.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 TSoundEngine.Information to get the details).

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

Source: audio/castlesoundengine_allocator.inc (line 135).

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.

Source: audio/castlesoundengine_engine.inc (line 192).

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.

Source: audio/castlesoundengine_engine.inc (line 199).

Public property Information: string read FInformation;

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

Source: audio/castlesoundengine_engine.inc (line 203).

Public property InformationSummary: string read FInformationSummary;

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

Source: audio/castlesoundengine_engine.inc (line 207).

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

Source: audio/castlesoundengine_engine.inc (line 289).

Public class property LogSoundLoading: Boolean read GetLogSoundLoading write SetLogSoundLoading;

This item has no description.

Source: audio/castlesoundengine_engine.inc (line 291).

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.

Source: audio/castlesoundengine_engine.inc (line 299).

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.

Source: audio/castlesoundengine_engine.inc (line 308).

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.

Source: audio/castlesoundengine_engine.inc (line 331).

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.

Source: audio/castlesoundengine_engine.inc (line 335).

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.

Source: audio/castlesoundengine_engine.inc (line 348).

Generated by PasDoc 0.17.0.snapshot.

Castle Game Engine

API Reference

Class TSoundEngine

Unit

Declaration

Description

Hierarchy

Overview

Constants

Fields

Methods

Properties

Description

Constants

Fields

Methods

Properties