Class TRepoSoundEngine

Unit

Declaration

type TRepoSoundEngine = class(TSoundEngine)

Description

Sound engine that keeps a repository of sounds, defined in a nice XML file. This allows to have simple Sound and Sound3D methods, that take a sound identifier (managing sound buffers will just happen automatically under the hood).

It extends TSoundEngine, so you can always still load new buffers and play them by TSoundEngine.LoadBuffer, TSoundEngine.PlaySound and all other methods. This only adds easy preloaded sounds, but you're not limited to them.

To initialize your sounds repository, you have to set the RepositoryURL property.

Hierarchy

Overview

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure LoadFromConfig(const Config: TCastleConfig); override;
Public procedure SaveToConfig(const Config: TCastleConfig); override;
Public procedure ReloadSounds;
Public function SoundFromName(const SoundName: string; const Required: boolean = true): TSoundType;
Public function Sound(SoundType: TSoundType; const Looping: boolean = false): TSound;
Public function Sound3D(SoundType: TSoundType; const Position: TVector3; const Looping: boolean = false): TSound; overload;
Public procedure AddSoundImportanceName(const Name: string; Importance: Integer);
Public procedure PrepareResources;

Properties

Public property RepositoryURL: string read FRepositoryURL write SetRepositoryURL;
Public property SoundsFileName: string read FRepositoryURL write SetRepositoryURL; deprecated;
Public property Sounds: TSoundInfoList read FSounds; deprecated 'do not use this, it is internal information';
Public property SoundImportanceNames: TStringList read FSoundImportanceNames;
Public property MusicPlayer: TLoopingChannel read GetMusicPlayer;
Public property LoopingChannel [constIndex:Cardinal]: TLoopingChannel read GetLoopingChannel;

Description

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public procedure LoadFromConfig(const Config: TCastleConfig); override;
 
Public procedure SaveToConfig(const Config: TCastleConfig); override;
 
Public procedure ReloadSounds;

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.

Public function SoundFromName(const SoundName: string; const Required: boolean = true): TSoundType;

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

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 stNone for missing sound. So the Required parameter only determines whether we make a warning, or not.

Public function Sound(SoundType: TSoundType; const Looping: boolean = false): TSound;

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

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

Public function Sound3D(SoundType: TSoundType; const Position: TVector3; const Looping: boolean = false): TSound; overload;

Play given sound at appropriate position in 3D space.

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

Public procedure AddSoundImportanceName(const Name: string; Importance: Integer);
 
Public procedure PrepareResources;

Opens sound context (OpenAL) 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 OpenAL, which on some systems may cause some warnings). If a game uses sound (through RepositoryURL), this will initialize OpenAL 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 do LoadBuffer or PlaySound, then sound context will be createdon-demand anyway. So calling this is always optional.

Properties

Public property RepositoryURL: string read FRepositoryURL write SetRepositoryURL;

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://castle-engine.io/creating_data_sound.php and engine examples for details (examples/audio/sample_sounds.xml contains an example file with lots of comments).

When you set RepositoryURL property, we read sound information from given XML file. You usually set RepositoryURL at the very beginning, before OpenAL context is initialized (although it's also Ok to do this after). Right after setting RepositoryURL you usually call SoundFromName a couple of times to convert some names into TSoundType values, to later use these TSoundType values with Sound and Sound3D methods.

When OpenAL is initialized, 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 (like the Sound and Sound3D methods) you have to set this property. For example like this:

SoundEngine.RepositoryURL := ApplicationData('sounds.xml');
stMySound1 := SoundEngine.SoundFromName('my_sound_1');
stMySound2 := SoundEngine.SoundFromName('my_sound_2');
// ... and later in your game you can do stuff like this:
SoundEngine.Sound(stMySound1);
SoundEngine.Sound3D(stMySound1, Vector3(0, 0, 10));

See CastleFilesUtils unit for docs of ApplicationData function.

Public property SoundsFileName: string read FRepositoryURL write SetRepositoryURL; deprecated;

Warning: this symbol is deprecated.

Deprecated name for RepositoryURL.

Public property Sounds: TSoundInfoList read FSounds; deprecated 'do not use this, it is internal information';

Warning: this symbol is deprecated: do not use this, it is internal information

A list of sounds used by your program. Each sound has a unique name, used to identify sound in the XML file and for SoundFromName function.

At the beginning, this list always contains exactly one sound: empty stNone. 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.

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 ALContextOpen, you can fill this list with values.

Initially, it contains a couple of useful values (ordered here from most to least important):

Public property MusicPlayer: TLoopingChannel read GetMusicPlayer;

Comfortable way to play and control the music. Simply assign MusicPlayer.Sound to play music. Set it to stNone to stop playing music. This is just a shortcut for LoopingChannel[0].

Public property LoopingChannel [constIndex:Cardinal]: TLoopingChannel read GetLoopingChannel;

Comfortable way to play and control looping sounds, like a music track. Using this is an alternative way to playing looping sounds using Sound with Looping=true parameter.

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

LoopingChannel[0].Sound := SoundFromName('my_music');

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

LoopingChannel[0].Sound := stNone;

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

All the looping channels (managed through this) play simultaneously, in addition to all other (looping and non-looping) sounds created by Sound.


Generated by PasDoc 0.15.0.