Castle Game EngineIntroduction Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers
|
Class TSoundEngine
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 OpenAL. You can explicitly initialize OpenAL context by ALContextOpen, and explicitly close it by ALContextClose. If you did not call ALContextOpen explicitly (that is, ALInitialized is False ), then the first LoadBuffer or TRepoSoundEngine.Sound or TRepoSoundEngine.Sound3D will automatically do it for you. If you do not call ALContextClose explicitly, then at destructor we'll do it automatically.
Hierarchy
Overview
Fields
Methods
 |
constructor Create; |
 |
destructor Destroy; override; |
 |
procedure ALContextOpen; |
 |
procedure ALContextClose; |
 |
procedure LoadFromConfig(const Config: TCastleConfig); override; |
 |
procedure SaveToConfig(const Config: TCastleConfig); override; |
 |
function ALVersionAtLeast(const AMajor, AMinor: Integer): boolean; override; |
 |
function GetContextString(Enum: TALCenum): string; |
 |
function LoadBuffer(const URL: string; const ExceptionOnError: boolean = true): TSoundBuffer; overload; |
 |
function LoadBuffer(const URL: string; out Duration: TFloatTime): TSoundBuffer; overload; deprecated 'use LoadBuffer without Duration parameter, and just read TSoundBuffer.Duration after loading'; |
 |
procedure FreeBuffer(var Buffer: TSoundBuffer); |
 |
function PlaySound(const Buffer: TSoundBuffer): TSound; overload; |
 |
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; |
 |
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'; |
 |
function PlaySound(const Parameters: TSoundParameters): TSound; overload; |
 |
procedure ParseParameters; |
 |
function ParseParametersHelp: string; |
 |
procedure UpdateListener(const Position, Direction, Up: TVector3); |
 |
function Devices: TSoundDeviceList; |
 |
function DeviceNiceName: string; deprecated 'use DeviceCaption'; |
 |
function DeviceCaption: string; |
Properties
Description
Fields
 |
internal const DefaultVolume = 1.0; |
|
 |
internal const DefaultDefaultRolloffFactor = 1.0; |
|
 |
internal const DefaultDefaultReferenceDistance = 1.0; |
|
 |
internal const DefaultDefaultMaxDistance = MaxSingle; |
|
 |
internal const DefaultDevice = ''; |
|
 |
internal const DefaultEnabled = true; |
|
Methods
 |
constructor Create; |
|
 |
destructor Destroy; override; |
|
 |
procedure ALContextOpen; |
Initialize sound engine. Initializes OpenAL library. Sets ALInitialized, ALActive, Information, EFXSupported.
You can set Device before calling this.
Note that we continue (without any exception) if the initialization failed for any reason (maybe OpenAL library is not available, or no sound output device is available). You can check ALActive and Information to know if the initialization was actually successfull. But you can also ignore it, the sound engine will silently (literally) keep working even if OpenAL could not be initialized.
|
 |
procedure ALContextClose; |
Release OpenAL resources. This sets ALInitialized and ALActive to False . It's allowed and harmless to call this when one of them is already False .
|
 |
function ALVersionAtLeast(const AMajor, AMinor: Integer): boolean; override; |
Is the OpenAL version at least AMajor.AMinor .
|
 |
function GetContextString(Enum: TALCenum): string; |
Wrapper for alcGetString.
|
 |
function LoadBuffer(const URL: string; const ExceptionOnError: boolean = true): TSoundBuffer; overload; |
Load a sound file contents such that they can be immediately played.
This method tries to initialize OpenAL context, and internally load the buffer contents to OpenAL. 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.
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.
|
 |
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 |
 |
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.
|
 |
function PlaySound(const Buffer: TSoundBuffer): TSound; overload; |
Play a sound from given buffer.
We use a smart OpenAL 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 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. |
 |
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; |
|
 |
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 |
 |
function ParseParametersHelp: string; |
Help string for options parsed by ParseParameters.
Note that it also lists the available OpenAL Devices, as they are valid arguments for the --audio-device option.
|
 |
procedure UpdateListener(const Position, Direction, Up: TVector3); |
Set OpenAL listener position and orientation.
|
 |
function Devices: TSoundDeviceList; |
List of available OpenAL sound devices. Read-only.
Use Devices[].Name as Device values. On some OpenAL implementations, some other Device values may be possible, e.g. old Loki implementation allowed some hints to be encoded in Lisp-like language inside the Device string.
|
 |
function DeviceNiceName: string; deprecated 'use DeviceCaption'; |
Warning: this symbol is deprecated: use DeviceCaption |
 |
function DeviceCaption: string; |
|
Properties
 |
property ALActive: boolean read FALActive; |
Do we have active OpenAL context. This is True when you successfully called ALContextOpen (and you didn't call ALContextClose yet). This also implies that OpenAL library is loaded.
|
 |
property ALInitialized: boolean read FALInitialized; |
Did we attempt to initialize OpenAL context. This indicates that ALContextOpen was called, and not closed with ALContextClose yet. Contrary to ALActive, this doesn't care if ALContextOpen was a success.
|
 |
property EFXSupported: boolean read FEFXSupported; |
Are OpenAL effects (EFX) extensions supported. Meaningful only when ALActive, that is it's initialized by ALContextOpen.
|
 |
property SoundInitializationReport: string read FInformation; deprecated 'use Information'; |
Warning: this symbol is deprecated: use Information |
 |
property Information: string read FInformation; |
|
 |
property OnOpenClose: TNotifyEventList read FOnOpenClose; |
Events fired after OpenAL context and device are being open or closed. More precisely, when ALInitialized changes (and so, possibly, ALActive changed).
|
 |
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.
|
 |
property Volume: Single read FVolume write SetVolume
default DefaultVolume; |
Sound volume, affects all OpenAL 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).
|
 |
property Device: string read FDevice write SetDevice; |
Sound output device, used when initializing OpenAL context.
You can change it even when OpenAL is already initialized. Then we'll close the old device (ALContextClose), change Device value, and initialize context again (ALContextOpen). Note that you will need to reload your buffers and sources again.
|
 |
property Enabled: boolean read FEnabled write SetEnabled default DefaultEnabled; |
Enable sound.
If False , then ALContextOpen will not initialize any OpenAL device. This is useful if you simply want to disable any sound output (or OpenAL usage), even when OpenAL library is available.
If the OpenAL context is already initialized when setting this, we will eventually close it. (More precisely, we will do ALContextClose and then ALContextOpen again. This behaves correctly.)
|
 |
property Enable : boolean read FEnabled write SetEnabled default DefaultEnabled; deprecated 'Use Enabled'; |
Warning: this symbol is deprecated: Use Enabled |
 |
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.
|
 |
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.15.0.
|