Class TRepoSoundEngine
Unit
CastleSoundEngine
Declaration
type TRepoSoundEngine = class(TSoundEngine)
Description
Sound engine that keeps a repository of sounds, defined in a nice XML file. Loading this XML file by setting RepositoryUrl property creates a number of TCastleSound instances, that you can find using SoundFromName method. You can use these TCastleSound instances e.g. with TSoundEngine.Play method.
This class extends TSoundEngine. So using the sounds defined in the XML file is completely optional. You can also create instances of TCastleSound and use them through any other means – by code, by setting them up in editor, see https://castle-engine.io/manual_sound.php .
Hierarchy
Overview
Methods
|
constructor Create; |
|
destructor Destroy; override; |
|
procedure ReloadSounds; deprecated 'deprecated just like RepositoryUrl'; |
|
function SoundFromName(const SoundName: string; const Required: boolean = true): TCastleSound; deprecated 'deprecated just like RepositoryUrl'; |
|
procedure PrepareResources; deprecated 'deprecated just like RepositoryUrl'; |
Properties
|
property RepositoryUrl: String read FRepositoryUrl write SetRepositoryUrl; deprecated 'instead of XML file, create design with .castle-component that contains a number of TCastleSound components'; |
|
property LoopingChannel [const Index: Cardinal]: TLoopingChannel
read GetLoopingChannel; |
Description
Methods
|
constructor Create; |
This item has no description. |
|
destructor Destroy; override; |
This item has no description. |
|
procedure ReloadSounds; deprecated 'deprecated just like RepositoryUrl'; |
Warning: this symbol is deprecated: deprecated just like RepositoryUrl
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.
|
|
function SoundFromName(const SoundName: string; const Required: boolean = true): TCastleSound; deprecated 'deprecated just like RepositoryUrl'; |
Warning: this symbol is deprecated: deprecated just like RepositoryUrl
Return sound with given name. Available names are given in SoundNames, defined in XML file pointed by RepositoryUrl. Always for SoundName = '' it will return nil.
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 nil for missing sound. So the Required parameter only determines whether we make a warning, or not.
|
|
procedure PrepareResources; deprecated 'deprecated just like RepositoryUrl'; |
Warning: this symbol is deprecated: deprecated just like RepositoryUrl
Opens sound context 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 sound context, which on some systems may cause some warnings). If a game uses sound (through RepositoryUrl), this will initialize sound backend 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 use Play, then sound context will be created on-demand anyway. So calling this is always optional.
|
Properties
|
property RepositoryUrl: String read FRepositoryUrl write SetRepositoryUrl; deprecated 'instead of XML file, create design with .castle-component that contains a number of TCastleSound components'; |
Warning: this symbol is deprecated: instead of XML file, create design with .castle-component that contains a number of TCastleSound components
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#section_sample .
When you set RepositoryUrl property, we read sound information from given XML file. You usually set RepositoryUrl at the very beginning of the application. Right after setting RepositoryUrl you usually call SoundFromName a couple of times to convert some names into TCastleSound values, to later use these TCastleSound values with Play or TCastleSoundSource.Sound.
When the sound context is initialized (or when you set this property, if the sound context is initialized already) then 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 you have to set this property. For example like this:
SoundEngine.RepositoryUrl := 'castle-data:/sounds.xml';
MySound1 := SoundEngine.SoundFromName('my_sound_1');
MySound2 := SoundEngine.SoundFromName('my_sound_2');
SoundEngine.Play(MySound1);
See https://castle-engine.io/data for information about the castle-data:/ protocol. In short, on desktop, this just indicates the "data" subdirectory of your project.
|
|
property LoopingChannel [const Index: Cardinal]: TLoopingChannel
read GetLoopingChannel; |
Comfortable way to play and control looping non-spatial sounds, like music tracks, ambience.
The TLoopingChannel instance automatically remembers the sound it plays. You start playing just by setting TLoopingChannel.Sound to some sound. For example:
LoopingChannel[0].Sound := MyMusicTrack;
You stop by setting TLoopingChannel.Sound to something else, which can be Nil to just stop playing any looping sound on this channel. For example:
LoopingChannel[0].Sound := nil;
Each channel has it's own TLoopingChannel.Volume that can be changed at any point.
All the looping channels play simultaneously.
Note: Alternative way to play looping non-spatial sounds is to use Play with TCastlePlayingSound (setting TCastlePlayingSound.Loop to True ).
|
Generated by PasDoc 0.16.0-snapshot.