Class TGameSoundEngine

DescriptionHierarchyFieldsMethodsProperties

Unit

GameSoundEngine

Declaration

type TGameSoundEngine = class(TObject)

Description

Easy to use sound manager, using OpenAL, ALUtils and ALSourceAllocator underneath.

At ALContextInit, right before initializing OpenAL stuff, this reads sounds information from SoundsXmlFileName file. When OpenAL is initialized, it loads all sound files. Sound filenames are specified inside SoundsXmlFileName file (they may be relative filenames, relative to the location of SoundsXmlFileName file).

So this assumes that you want to load all sound files at once (along with initializing OpenAL context) and free them at once when releasing AL context. And it requires that you place your sounds data and XML file in appropriate locations.

So the basic principle of this unit is to load all files at once, and require file like sounds/index.xml. That's the price for having easy and comfortable unit. All these assumptions are perfectly OK for most games, for more general sound programs... not necessarily. If you need more flexibility, you should write your own sound manager (or heavily extend this), using ALUtils and ALSourceAllocator units directly.

Hierarchy

Overview

Methods

Public constructor Create;
Public destructor Destroy; override;
Public function SoundFromName(const SoundName: string): TSoundType;
Public procedure ALContextInit(WasParam_NoSound: boolean); virtual;
Public procedure ALRefreshUsedSources;
Public procedure ALContextClose;
Public procedure AppendALInformation(S: TStrings);
Public function ALInformation: string;
Public function Sound(SoundType: TSoundType; const Looping: boolean = false): TALAllocatedSource;
Public function Sound3d(SoundType: TSoundType; const Position: TVector3Single; const Looping: boolean = false): TALAllocatedSource; overload;
Public procedure AddSoundImportanceName(const Name: string; Importance: Integer);
Public procedure ReadSoundInfos;
Public procedure LoadFromConfig(ConfigFile: TKamXMLConfig);
Public procedure SaveToConfig(ConfigFile: TKamXMLConfig);
Public procedure ALChangeDevice(const NewALCDevice: string);

Properties

Public property SoundsXmlFileName: string read FSoundsXmlFileName write FSoundsXmlFileName;
Public property SoundNames: TStringList read FSoundNames;
Public property SoundVolume: Single read GetSoundVolume write SetSoundVolume default DefaultSoundVolume;
Public property SoundImportanceNames: TStringList read FSoundImportanceNames;
Public property SoundInitializationReport: string read FSoundInitializationReport;
Public property MusicPlayer: TMusicPlayer read FMusicPlayer;
Public property ALMinAllocatedSources: Cardinal read GetALMinAllocatedSources write SetALMinAllocatedSources default DefaultALMinAllocatedSources;
Public property ALMaxAllocatedSources: Cardinal read GetALMaxAllocatedSources write SetALMaxAllocatedSources default DefaultALMaxAllocatedSources;

Description

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public function SoundFromName(const SoundName: string): TSoundType;

Return sound with given name. Available names are given in SoundNames, and inside ../data/sounds/index.xml. Always for SoundName = '' it will return stNone.

Exceptions raised
Exception
On invalid SoundName
Public procedure ALContextInit(WasParam_NoSound: boolean); virtual;

Call this always to initialize OpenAL and OpenAL context, and load sound files. This sets SoundInitializationReport and ALActive.

You can set ALCDevice before calling this.

Public procedure ALRefreshUsedSources;

This will call RefreshUsed on internal ALSourceAllocator, see TALSourceAllocator.RefreshUsed for info. It's silently ignored when not ALActive.

Public procedure ALContextClose;

Call this always to release OpenAL things. This is ignored if not ALActive.

Public procedure AppendALInformation(S: TStrings);

If ALActive, then will append some info about current OpenAL used.

Public function ALInformation: string;
 
Public function Sound(SoundType: TSoundType; const Looping: boolean = false): TALAllocatedSource;

Play given sound. This should be used to play sounds that are not spatial actually, i.e. have no place in 3D space.

Returns used TALAllocatedSource (or nil if none was available). You don't have to do anything with this returned TALAllocatedSource.

Public function Sound3d(SoundType: TSoundType; const Position: TVector3Single; const Looping: boolean = false): TALAllocatedSource; overload;

Play given sound at appropriate position in 3D space.

Returns used TALAllocatedSource (or nil if none was available). You don't have to do anything with this returned TALAllocatedSource.

Public procedure AddSoundImportanceName(const Name: string; Importance: Integer);
 
Public procedure ReadSoundInfos;
 
Public procedure LoadFromConfig(ConfigFile: TKamXMLConfig);

These methods load/save into config file some sound properties. Namely: sound/music volume, min/max allocated sounds, and current ALCDevice. ALCDevice is technically declared in another unit, ALUtils, but still this is probably the best place to save/load it.

Everything is loaded/saved under the path sound/ inside ConfigFile.

Public procedure SaveToConfig(ConfigFile: TKamXMLConfig);
 
Public procedure ALChangeDevice(const NewALCDevice: string);

Change ALCDevice while OpenAL is already initialized. This cleanly closes the old device (ALContextClose), changes ALCDevice value, initializes context again (ALContextInit).

Properties

Public property SoundsXmlFileName: string read FSoundsXmlFileName write FSoundsXmlFileName;

The XML file that contains description of your sounds. See examples/sample_sounds.xml file for a heavily commented example.

It's crucial that you create such file, and eventually adjust this property before calling ReadSoundInfos (or ALContextInit, that always callsReadSoundInfos).

By default (in our constryctor) this is initialized to ProgramDataPath + 'data' + PathDelim + 'sounds' + PathDelim + 'index.xml' which may be good location for most games.

Public property SoundNames: TStringList read FSoundNames;

This is a list of sound names used by your game. Each sound has a unique name, used to identify sound in sounds/index.xml file and for SoundFromName function. These names are stored here.

At the beginning, this list always contains exactly one item: empty string. This is a special "sound type" that has index 0 (should be always expressed as TSoundType value stNone) and name ''. stNone is a special sound as it actually means "no sound" in many cases.

You can (and should !) fill this array with all sound names your game is using before calling ALContextInit (or ReadSoundInfos, but ReadSoundInfos is usually called for the first time by ALContextInit).

TODO: in the future this may be automatically filled when ReadSoundInfos is called. For now, ReadSoundInfos just read sounds information for all sounds mentioned here — in the future, ReadSoundInfos may also just fill this list.

Public property SoundVolume: Single read GetSoundVolume write SetSoundVolume default DefaultSoundVolume;

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

Public property SoundImportanceNames: TStringList read FSoundImportanceNames;

Sound importance names and values. Each item is a name (as a string) and a value (that is stored in Objects property of the item as a pointer; add new importances by AddSoundImportanceName for comfort).

These can be used within sounds.xml file. Before using ALContextInit, you can fill this list with values. Initially, it contains only the 'max' value associated with MaxSoundImportance.

Public property SoundInitializationReport: string read FSoundInitializationReport;
 
Public property MusicPlayer: TMusicPlayer read FMusicPlayer;
 
Public property ALMinAllocatedSources: Cardinal read GetALMinAllocatedSources write SetALMinAllocatedSources default DefaultALMinAllocatedSources;

Min/max number of allocated OpenAL sources.

These properties are used when creating TALSourceAllocator. When TALSourceAllocator is already created, these properties correspond to allocator properties (setting them sets also allocator properties).

In summary, you can treat these properties just like analogous TALSourceAllocator properties, but you can freely operate on them even when OpenAL is not initialized. Which is useful if user disabled sound or you want to load/save these values from some config files at time when OpenAL couldn't be initialized yet — in such cases AL allocator doesn't exist, but you can operate on these properties without worry.

When changing Min/MaxAllocatedSources, remember to always keep MinAllocatedSources <= MaxAllocatedSources.

Public property ALMaxAllocatedSources: Cardinal read GetALMaxAllocatedSources write SetALMaxAllocatedSources default DefaultALMaxAllocatedSources;
 
Generated by PasDoc 0.10.0 on 2008-02-25 00:00:30