Castle Game Engine: CastleSoundEngine: Class TRepoSoundEngine

# Class TRepoSoundEngine
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleSoundEngine ## 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 TObject TSoundAllocator TSoundEngine TRepoSoundEngine ## Overview ### Methods
| `procedure LoadFromConfig(const Config: TCastleConfig); override;`
| `procedure SaveToConfig(const Config: TCastleConfig); override;`
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure ALContextOpen; override;`
| `procedure ALContextClose; override;`
| `procedure ReloadSounds;`
| `function SoundFromName(const SoundName: string; const RaiseError: boolean = true): TSoundType;`
| `function Sound(SoundType: TSoundType; const Looping: boolean = false): TSound;`
| `function Sound3D(SoundType: TSoundType; const Position: TVector3Single; const Looping: boolean = false): TSound; overload;`
| `procedure AddSoundImportanceName(const Name: string; Importance: Integer);`
### Properties
| `property RepositoryURL: string read FRepositoryURL write SetRepositoryURL;`
| `property SoundsFileName: string read FRepositoryURL write SetRepositoryURL; deprecated;`
| `property Sounds: TSoundInfoList read FSounds;`
| `property SoundImportanceNames: TStringList read FSoundImportanceNames;`
| `property MusicPlayer: TMusicPlayer read FMusicPlayer;`
## Description ### Methods
| `procedure LoadFromConfig(const Config: TCastleConfig); override;`
| `procedure SaveToConfig(const Config: TCastleConfig); override;`
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure ALContextOpen; override;`
In addition to initializing OpenAL context, this also loads sound files.
| `procedure ALContextClose; override;`
| `procedure ReloadSounds;`
Reload the RepositoryURL and all referenced buffers. Useful as a tool for 3D data designers, to reload the sounds XML file without restarting the game/sound engine etc.
| `function SoundFromName(const SoundName: string; const RaiseError: 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. ###### Exceptions raised `Exception` On invalid SoundName when RaiseError = `True`.
| `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.
| `function Sound3D(SoundType: TSoundType; const Position: TVector3Single; 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.
| `procedure AddSoundImportanceName(const Name: string; Importance: Integer);`
### Properties
| `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 http://castle-engine.sourceforge.net/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, Vector3Single(0, 0, 10));
See CastleFilesUtils unit for docs of ApplicationData function.
| `property SoundsFileName: string read FRepositoryURL write SetRepositoryURL; deprecated;`
Warning: this symbol is deprecated. Deprecated name for RepositoryURL.
| `property Sounds: TSoundInfoList read FSounds;`
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.
| `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): 'max' - MaxSoundImportance 'level_event' - LevelEventSoundImportance 'player' - PlayerSoundImportance 'default_creature' - DefaultCreatureSoundImportance 'minor_non_spatial' - MinorNonSpatialSoundImportance
| `property MusicPlayer: TMusicPlayer read FMusicPlayer;`
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:12