Class TRepoSoundEngine

Description
Hierarchy
Constants
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TRepoSoundEngine = class(TSoundEngine)

Description

Sound engine that keeps a repository of sounds, defined in a nice XML file. Loading this XML file by setting RepositoryUrl property creates a number of TCastleSound instances, that you can find using SoundFromName method. You can use these TCastleSound instances e.g. with TSoundEngine.Play method.

This class extends TSoundEngine. So using the sounds defined in the XML file is completely optional. You can also create instances of TCastleSound and use them through any other means – by code, by setting them up in editor, see https://castle-engine.io/sound .

Source: audio/castlesoundengine_repoengine.inc (line 34).

Hierarchy

Show Additional Members:

Overview

Constants

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 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;
Public constructor Create;
Public destructor Destroy; override;
Public procedure ReloadSounds; deprecated 'deprecated just like RepositoryUrl';
Public function SoundFromName(const SoundName: string; const Required: boolean = true): TCastleSound; deprecated 'deprecated just like RepositoryUrl';
Public procedure PrepareResources; deprecated 'deprecated just like RepositoryUrl';

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;
Public property RepositoryUrl: String read FRepositoryUrl write SetRepositoryUrl; deprecated 'instead of XML file, create design with .castle-component that contains a number of TCastleSound components';
Public property LoopingChannel [const Index: Cardinal]: TLoopingChannel read GetLoopingChannel;

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 is declared in ancestor TSoundEngine.

This item has no description.

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

Public DefaultDistanceModel = dmInverse;

This item is declared in ancestor TSoundEngine.

This item has no description.

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

Public DefaultDevice = '';

This item is declared in ancestor TSoundEngine.

This item has no description.

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

Public DefaultEnabled = true;

This item is declared in ancestor TSoundEngine.

This item has no description.

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

Fields

Public class var LogVerbose: Boolean;

This item is declared in ancestor TSoundEngine.

This item has no description.

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

Methods

Public procedure ContextOpen;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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.

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

Public procedure ParseParameters;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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 is declared in ancestor TSoundEngine.

This item has no description.

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

Public constructor Create;

This item has no description.

Source: audio/castlesoundengine_repoengine.inc (line 173).

Public destructor Destroy; override;

This item has no description.

Source: audio/castlesoundengine_repoengine.inc (line 174).

Public procedure ReloadSounds; deprecated 'deprecated just like RepositoryUrl';

Warning: this symbol is deprecated: deprecated just like RepositoryUrl

Reload the RepositoryUrl and all referenced buffers. Useful as a tool for game designers, to reload the sounds XML file without restarting the game and sound engine.

Source: audio/castlesoundengine_repoengine.inc (line 218).

Public function SoundFromName(const SoundName: string; const Required: boolean = true): TCastleSound; deprecated 'deprecated just like RepositoryUrl';

Warning: this symbol is deprecated: deprecated just like RepositoryUrl

Return sound with given name. Available names are given in SoundNames, defined in XML file pointed by RepositoryUrl. Always for SoundName = '' it will return nil.

Parameters
Required

If Required = True, it will make a warning when the sound name is not found. This may mean that sound is missing in your sounds.xml file (so you should correct your sounds.xml), or that you didn't load the sounds.xml file yet (so you should correct your code to set TRepoSoundEngine.RepositoryUrl early enough), or that you specified invalid sound name. When Required = False, missing sound is silently ignored, which is sensible if it was optional.

Regardless of the Required value, we return nil for missing sound. So the Required parameter only determines whether we make a warning, or not.

Source: audio/castlesoundengine_repoengine.inc (line 240).

Public procedure PrepareResources; deprecated 'deprecated just like RepositoryUrl';

Warning: this symbol is deprecated: deprecated just like RepositoryUrl

Opens sound context and loads sound files, but only if RepositoryUrl was set and contains some sounds.

The idea is that you can call this during "loading" stage for any game that *possibly but not necessarily* uses sound. If a game doesn't use sound, this does nothing (doesn't waste time to even initialize sound context, which on some systems may cause some warnings). If a game uses sound (through RepositoryUrl), this will initialize sound backend and load these sound files, to play them without any delay in game.

Note that, if this does nothing, but you later set RepositoryUrl or use Play, then sound context will be created on-demand anyway. So calling this is always optional.

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

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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

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

Public property InformationSummary: string read FInformationSummary;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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 is declared in ancestor TSoundEngine.

This item has no description.

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

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

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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;

This item is declared in ancestor TSoundEngine.

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

Public property RepositoryUrl: String read FRepositoryUrl write SetRepositoryUrl; deprecated 'instead of XML file, create design with .castle-component that contains a number of TCastleSound components';

Warning: this symbol is deprecated: instead of XML file, create design with .castle-component that contains a number of TCastleSound components

The XML file that contains description of your sounds. This should be an URL (in simple cases, just a filename) pointing to an XML file describing your sounds. See https://github.com/castle-engine/cge-www/blob/master/htdocs/doc/obsolete/deprecated_3d_game_utilities/creating_data_sound.php .

When you set RepositoryUrl property, we read sound information from given XML file. You usually set RepositoryUrl at the very beginning of the application. Right after setting RepositoryUrl you usually call SoundFromName a couple of times to convert some names into TCastleSound values, to later use these TCastleSound values with Play or TCastleSoundSource.Sound.

When the sound context is initialized (or when you set this property, if the sound context is initialized already) then sound buffers will actually be loaded.

If this is empty (the default), then no sounds are loaded, and TRepoSoundEngine doesn't really give you much above standard TSoundEngine.

If you want to actually use TRepoSoundEngine features you have to set this property. For example like this: 

SoundEngine.RepositoryUrl := 'castle-data:/sounds.xml';
MySound1 := SoundEngine.SoundFromName('my_sound_1');
MySound2 := SoundEngine.SoundFromName('my_sound_2');
// ... and later in your game you can do stuff like this:
SoundEngine.Play(MySound1);

See https://castle-engine.io/data for information about the castle-data:/ protocol. In short, on desktop, this just indicates the "data" subdirectory of your project.

Source: audio/castlesoundengine_repoengine.inc (line 212).

Public property LoopingChannel [const Index: Cardinal]: TLoopingChannel read GetLoopingChannel;

Comfortable way to play and control looping non-spatial sounds, like music tracks, ambience.

The TLoopingChannel instance automatically remembers the sound it plays. You start playing just by setting TLoopingChannel.Sound to some sound. For example: 

LoopingChannel[0].Sound := MyMusicTrack;

You stop by setting TLoopingChannel.Sound to something else, which can be Nil to just stop playing any looping sound on this channel. For example: 

LoopingChannel[0].Sound := nil;

Each channel has it's own TLoopingChannel.Volume that can be changed at any point.

All the looping channels play simultaneously.

Note: Alternative way to play looping non-spatial sounds is to use Play with TCastlePlayingSound (setting TCastlePlayingSound.Loop to True).

Source: audio/castlesoundengine_repoengine.inc (line 265).

Generated by PasDoc 0.17.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.