Castle Game Engine

Class TSoundEngine

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleSoundEngine

Declaration

type TSoundEngine = class(TSoundAllocator)

Description

Sound engine, responsible for loading and playing sound.

There should always be only one instance of this class, accessed through the global SoundEngine variable. See docs at SoundEngine for more details.

The sound engine is actually a wrapper over a backend, like OpenAL. You can explicitly initialize OpenAL context by ContextOpen, and explicitly close it by ContextClose. If you did not call ContextOpen explicitly (that is, IsContextOpen is False), then the first LoadBuffer or TRepoSoundEngine.Sound or TRepoSoundEngine.Sound3D will automatically do it for you. If you do not call ContextClose explicitly, then at destructor we'll do it automatically.

Hierarchy

Overview

Fields

Public nested const DefaultVolume = 1.0;
Public nested const DefaultDefaultRolloffFactor = 1.0;
Public nested const DefaultDefaultReferenceDistance = 1.0;
Public nested const DefaultDefaultMaxDistance = MaxSingle;
Public nested const DefaultDistanceModel = dmLinearDistanceClamped;
Public nested const DefaultDevice = '';
Public nested const DefaultEnabled = true;

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure ContextOpen;
Public procedure ContextClose;
Public procedure ALContextOpen; deprecated 'use ContextOpen';
Public procedure ALContextClose; deprecated 'use ContextClose';
Public procedure LoadFromConfig(const Config: TCastleConfig); override;
Public procedure SaveToConfig(const Config: TCastleConfig); override;
Public function LoadBuffer(const URL: string; const SoundLoading: TSoundLoading; const ExceptionOnError: Boolean = true): TSoundBuffer; overload;
Public function LoadBuffer(const URL: string; const ExceptionOnError: Boolean = true): TSoundBuffer; overload;
Public function LoadBuffer(const URL: string; out Duration: TFloatTime): TSoundBuffer; overload; deprecated 'use LoadBuffer without Duration parameter, and just read TSoundBuffer.Duration after loading';
Public procedure FreeBuffer(var Buffer: TSoundBuffer);
Public function PlaySound(const Buffer: TSoundBuffer): TSound; overload;
Public function PlaySound(const Buffer: TSoundBuffer; const Spatial, Looping: boolean; const Importance: Cardinal; const Gain, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single = 1): TSound; overload;
Public function PlaySound(const Buffer: TSoundBuffer; const Spatial, Looping: boolean; const Importance: Cardinal; const Gain, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single; const ReferenceDistance: Single; const MaxDistance: Single): TSound; overload; deprecated 'use PlaySound that gets TSoundParameters instance';
Public function PlaySound(const Parameters: TSoundParameters): TSound; overload;
Public procedure ParseParameters;
Public function ParseParametersHelp: string;
Public procedure UpdateListener(const Position, Direction, Up: TVector3);
Public function Devices: TSoundDeviceList;
Public function DeviceNiceName: string; deprecated 'use DeviceCaption';
Public function DeviceCaption: string;

Properties

Public property InternalBackend: TSoundEngineBackend read Backend write SetInternalBackend;
Public property IsContextOpenSuccess: boolean read FIsContextOpenSuccess;
Public property ALActive: boolean read FIsContextOpenSuccess; deprecated 'use IsContextOpenSuccess';
Public property IsContextOpen: boolean read FIsContextOpen;
Public property ALInitialized: Boolean read FIsContextOpen; deprecated 'use IsContextOpen';
Public property SoundInitializationReport: string read FInformation; deprecated 'use Information';
Public property Information: string read FInformation;
Public property OnOpenClose: TNotifyEventList read FOnOpenClose;
Public property EnableSaveToConfig: boolean read FEnableSaveToConfig write FEnableSaveToConfig default true;
Public class property LogSoundLoading: Boolean read GetLogSoundLoading write SetLogSoundLoading;
Public property InitialPitchMultiplier: Single read FInitialPitchMultiplier write FInitialPitchMultiplier default 1.0;
Published property Volume: Single read FVolume write SetVolume default DefaultVolume;
Published property Device: string read FDevice write SetDevice;
Published property Enabled: boolean read FEnabled write SetEnabled default DefaultEnabled;
Published property Enable: boolean read FEnabled write SetEnabled default DefaultEnabled; deprecated 'Use Enabled';
Published property DefaultRolloffFactor: Single read FDefaultRolloffFactor write FDefaultRolloffFactor default DefaultDefaultRolloffFactor;
Published property DefaultReferenceDistance: Single read FDefaultReferenceDistance write FDefaultReferenceDistance default DefaultDefaultReferenceDistance;
Published property DefaultMaxDistance: Single read FDefaultMaxDistance write FDefaultMaxDistance default DefaultDefaultMaxDistance;
Published property DistanceModel: TSoundDistanceModel read FDistanceModel write SetDistanceModel default DefaultDistanceModel;

Description

Fields

Public nested const DefaultVolume = 1.0;
 
Public nested const DefaultDefaultRolloffFactor = 1.0;
 
Public nested const DefaultDefaultReferenceDistance = 1.0;
 
Public nested const DefaultDefaultMaxDistance = MaxSingle;
 
Public nested const DefaultDistanceModel = dmLinearDistanceClamped;
 
Public nested const DefaultDevice = '';
 
Public nested const DefaultEnabled = true;
 

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public procedure ContextOpen;

Initialize sound engine. Initializes sound backend (like OpenAL library). Sets IsContextOpen, IsContextOpenSuccess, Information.

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.

Public procedure ContextClose;

Release sound backend resources. This sets IsContextOpen and IsContextOpenSuccess to False. It's allowed and harmless to call this when one of them is already False.

Public procedure ALContextOpen; deprecated 'use ContextOpen';

Warning: this symbol is deprecated: use ContextOpen

 
Public procedure ALContextClose; deprecated 'use ContextClose';

Warning: this symbol is deprecated: use ContextClose

 
Public procedure LoadFromConfig(const Config: TCastleConfig); override;
 
Public procedure SaveToConfig(const Config: TCastleConfig); override;
 
Public function LoadBuffer(const URL: string; const SoundLoading: TSoundLoading; const ExceptionOnError: Boolean = true): TSoundBuffer; overload;

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) TSoundBuffer instance. The PlaySound must be ready anyway to always load the buffer on-demand (because OpenAL context may be lost while the game is ongoing, in case of Android).

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
ExceptionOnError
When to raise exception, or merely make a warning by WritelnWarning, in case of error when loading.

Note that it always returns non-nil, even in case of ExceptionOnError=False and an error at loading. But in this case, TSoundBuffer is mostly a useless empty instance. Do not depend on this behavior, and check for Nil result in case you use ExceptionOnError=False.

SoundLoading
Specifies whether to load sound at once, or use streaming. See TSoundLoading for details.
Exceptions raised
ESoundFileError
If loading of this sound file failed. There are many reasons why this may happen: we cannot read given URL, or it may contain invalid contents, or a library required to decompress e.g. OggVorbis is missing.
Public function LoadBuffer(const URL: string; const ExceptionOnError: Boolean = true): TSoundBuffer; overload;
 
Public function LoadBuffer(const URL: string; out Duration: TFloatTime): TSoundBuffer; overload; deprecated 'use LoadBuffer without Duration parameter, and just read TSoundBuffer.Duration after loading';

Warning: this symbol is deprecated: use LoadBuffer without Duration parameter, and just read TSoundBuffer.Duration after loading

 
Public procedure FreeBuffer(var Buffer: TSoundBuffer);

Free a sound file buffer. Ignored when buffer is Nil. Buffer is always set to Nil after this.

Exceptions raised
ESoundBufferNotLoaded
When invalid (not Nil, and not returned by LoadBuffer) buffer identifier is given.
Public function PlaySound(const Buffer: TSoundBuffer): TSound; overload;

Play a sound from given buffer.

We use a smart sound allocator, so the sound will be actually played only if resources allow. Use higher Importance to indicate sounds that are more important to play.

We set the sound properties and start playing it.

Both spatialized (3D) and not spatialized sounds are possible. See the TSoundParameters for a full list of sound parameters. You can pass all the sound parameters as a TSoundParameters instance. You can destroy the TSoundParameters instance right after calling this method, the reference to it is not saved anywhere.

Returns

The allocated sound as TSound.

Returns Nil when there were no resources to play another sound (and it wasn't important enough to override another sound). Always returns Nil when SoundBuffer is zero (indicating that buffer was not loaded).

In simple cases you can just ignore the result of this method. In advanced cases, you can use it to observe and update the sound later.

Public function PlaySound(const Buffer: TSoundBuffer; const Spatial, Looping: boolean; const Importance: Cardinal; const Gain, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single = 1): TSound; overload;
 
Public function PlaySound(const Buffer: TSoundBuffer; const Spatial, Looping: boolean; const Importance: Cardinal; const Gain, MinGain, MaxGain: Single; const Position: TVector3; const Pitch: Single; const ReferenceDistance: Single; const MaxDistance: Single): TSound; overload; deprecated 'use PlaySound that gets TSoundParameters instance';

Warning: this symbol is deprecated: use PlaySound that gets TSoundParameters instance

 
Public function PlaySound(const Parameters: TSoundParameters): TSound; overload;
 
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 Enable to False).

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

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.

Public procedure UpdateListener(const Position, Direction, Up: TVector3);

Set the sound listener position and orientation.

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.

Public function DeviceNiceName: string; deprecated 'use DeviceCaption';

Warning: this symbol is deprecated: use DeviceCaption

 
Public function DeviceCaption: string;
 

Properties

Public property InternalBackend: TSoundEngineBackend read Backend write SetInternalBackend;

Sound backend, like OpenAL or FMOD or SOX. Do not change or access this yourself. You can change this only by calling procedure like UseFMODSoundBackend from CastleFMODSoundBackend unit.

Public property IsContextOpenSuccess: boolean read FIsContextOpenSuccess;

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

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

Public property ALActive: boolean read FIsContextOpenSuccess; deprecated 'use IsContextOpenSuccess';

Warning: this symbol is deprecated: use IsContextOpenSuccess

 
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.

Public property ALInitialized: Boolean read FIsContextOpen; deprecated 'use IsContextOpen';

Warning: this symbol is deprecated: use IsContextOpen

 
Public property SoundInitializationReport: string read FInformation; deprecated 'use Information';

Warning: this symbol is deprecated: use Information

 
Public property Information: string read FInformation;
 
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).

Public property EnableSaveToConfig: boolean read FEnableSaveToConfig write FEnableSaveToConfig default true;

Should we save Enable to config file in SaveToConfig call. This is always reset to True after setting Enable value.

Public class property LogSoundLoading: Boolean read GetLogSoundLoading write SetLogSoundLoading;
 
Public property InitialPitchMultiplier: Single read FInitialPitchMultiplier write FInitialPitchMultiplier default 1.0;

Newly played sounds will have TSound.Pitch multiplied by this.

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

Sound volume, affects all sounds (effects and music). This must always be within 0..1 range. 0.0 means that there are no effects (this case should be optimized).

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

Published property Enabled: boolean read FEnabled write SetEnabled default DefaultEnabled;

Enable sound.

If False, then ContextOpen will not initialize any device. 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.

If the sound context is already initialized when setting this, we will eventually close it. (More precisely, we will do ContextClose and then ContextOpen again. This behaves correctly.)

Published property Enable: boolean read FEnabled write SetEnabled default DefaultEnabled; deprecated 'Use Enabled';

Warning: this symbol is deprecated: Use Enabled

 
Published property DefaultRolloffFactor: Single read FDefaultRolloffFactor write FDefaultRolloffFactor default DefaultDefaultRolloffFactor;

How the sound is attenuated with the distance. These are used only for spatialized sounds created with PlaySound. The DefaultReferenceDistance and DefaultMaxDistance values are used only if you don't supply explicit values to PlaySound.

The exact interpretation of these depends on current DistanceModel. See OpenAL specification for exact equations. In short:

  • Smaller Rolloff Factor makes the attenuation weaker. In particular 0 turns off attenuation by distance. Default is 1.

  • Reference Distance is the distance at which exactly sound gain is heard. Default is 1.

  • Max Distance interpretation depends on the model. For "inverse clamped model", the gain is no longer scaled down after reaching this distance. For linear models, the gain reaches zero at this distance. Default is maximum float (I don't know the interpretation of this for linear model).

Our default values follow OpenAL default values.

Published property DefaultReferenceDistance: Single read FDefaultReferenceDistance write FDefaultReferenceDistance default DefaultDefaultReferenceDistance;
 
Published property DefaultMaxDistance: Single read FDefaultMaxDistance write FDefaultMaxDistance default DefaultDefaultMaxDistance;
 
Published property DistanceModel: TSoundDistanceModel read FDistanceModel write SetDistanceModel default DefaultDistanceModel;

How the sources are spatialized. For precise meaning, see OpenAL specification of alDistanceModel.

Note that some models are actually available only since OpenAL 1.1 version. Older OpenAL versions may (but don't have to) support them through extensions. We will internally do everything possible to request given model, but eventually may fallback on some other model. This probably will not be a problem in practice, as all modern OS versions (Linux distros, Windows OpenAL installers etc.) include OpenAL 1.1.

The default distance model, DefaultDistanceModel, is the linear model most conforming to VRML/X3D sound requirements. You can change it if you want (for example, OpenAL default is dmInverseDistanceClamped).

Generated by PasDoc 0.16.0.