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 things like ALActive and SoundInitializationReport, but generally this class will hide from you the fact that sound is not initialized.
procedure ALContextClose; override;
Release OpenAL context and resources.
ALInitialized and ALActive are set to False. It's allowed and harmless to cal this when one of them is already False.
function GetContextString(Enum: TALCenum): string;
Result is 0 only if we don't have a valid OpenAL context. Note that this method will automatically call ALContextOpen if it wasn't called yet. So result = zero means that ALContextOpen was called, but for some reason failed.
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. (And OpenAL would also free the buffer anyway at closing, although some OpenAL versions could write a warning about this.)
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 OpenAL buffer. The buffer is released only once you call FreeBuffer as many times as you called LoadBuffer for it.
function LoadBuffer(const URL: string): TSoundBuffer;
When invalid (not zero, and not returned by LoadBuffer) buffer identifier is given.
function PlaySound(const Buffer: TSoundBuffer; const Spatial, Looping: boolean; const Importance: Cardinal; const Gain, MinGain, MaxGain: Single; const Position: TVector3Single; const Pitch: Single = 1): TSound;
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. When Spatial = False, then Position is ignored (you can pass anything, like ZeroVector3Single).
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.
Parse parameters in Parameters and interprets and removes recognized options. Internally it uses Parameters.Parse with ParseOnlyKnownLongOptions = True. Recognized options:
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;
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, that is ALInited = True.
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.
Events fired after OpenAL context and device are being open or closed. More precisely, when ALInitialized changes (and so, possibly, ALActive changed).
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).
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.
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 DefaultRolloffFactor: Single
read FDefaultRolloffFactor write FDefaultRolloffFactor default DefaultDefaultRolloffFactor;
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 DefaultReferenceDistance: Single
read FDefaultReferenceDistance write FDefaultReferenceDistance default DefaultDefaultReferenceDistance;
property DefaultMaxDistance: Single
read FDefaultMaxDistance write FDefaultMaxDistance default DefaultDefaultMaxDistance;
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).