Class TCastleSound
Unit
Declaration
type TCastleSound = class(TCastleComponent)
Description
Sound that can be loaded from Url (possibly reusing a cache, possibly using streaming) and played.
Aside from sound file (also called "sound buffer" or "audio clip" in various APIs) this class allows to configue also playback values, like Volume and Pitch. These playback values are intended to reflect preferences specific to this sound file. They are multiplied by playback values of the TCastleSoundSource (TCastleSoundSource.Volume, TCastleSoundSource.Pitch) and TCastlePlayingSound (to adjust it per-playback, using TCastlePlayingSound.Volume, TCastlePlayingSound.Pitch).
This class does not actually play the sound. It only defines something that can be played. To play the sound use SoundEngine.Play or TCastleSoundSource. For spatial sounds, attach TCastleSoundSource to a TCastleTransform within some TCastleViewport and set TCastleSoundSource.Sound or call TCastleSoundSource.Play.
Source: audio/castlesoundengine_sound.inc (line 59).
Hierarchy
- TObject
- TPersistent
- TComponent
- TCastleComponent
- TCastleSound
Overview
Constants
| Public | DefaultReferenceDistance = 1.0; |
| Public | DefaultMaxDistance = 10000.0; |
Methods
| Protected | function GetInternalText: String; virtual; |
| Protected | procedure SetInternalText(const Value: String); virtual; |
| Protected | procedure SetName(const Value: TComponentName); override; |
| Protected | procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual; |
| Public | procedure CustomSerialization(const SerializationProcess: TSerializationProcess); virtual; |
| Public | procedure SetTransient; |
| Public | procedure AddNonVisualComponent(const NonVisualComponent: TComponent); |
| Public | procedure InsertNonVisualComponent(const Index: Integer; const NonVisualComponent: TComponent); |
| Public | procedure RemoveNonVisualComponent(const NonVisualComponent: TComponent); |
| Public | function NonVisualComponentsIndexOf(const NonVisualComponent: TComponent): Integer; |
| Public | function NonVisualComponentsCount: Integer; |
| Public | function NonVisualComponentsEnumerate: TNonVisualComponentsEnumerator; |
| Public | function ValueIsStreamed: Boolean; virtual; |
| Public | procedure DesignerInfo(const SList: TStrings); virtual; |
| Public | procedure DesignerWarnings(const SList: TStrings); virtual; |
| Protected | procedure Loaded; override; |
| Public | constructor Create(AOwner: TComponent); override; |
| Public | destructor Destroy; override; |
| Public | function PropertySections(const PropertyName: String): TPropertySections; override; |
| Public | procedure LoadFromStream(const AStream: TStream; const MimeType: String); |
| Public | function Duration: Single; |
| Public | function DataFormat: TSoundDataFormat; |
| Public | function Frequency: Cardinal; |
Properties
| Public | property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents; |
| Public | property IsLoading: Boolean read FIsLoading; |
| Public | property MinGain: Single read FMinGain write SetMinGain default 0.0; platform; |
| Public | property MaxGain: Single read FMaxGain write SetMaxGain default 1.0; platform; |
| Published | property Url: String read FUrl write SetUrl; |
| Published | property Stream: Boolean read FStream write SetStream default false; |
| Published | property Volume: Single read FVolume write SetVolume default 1.0; |
| Published | property Pitch: Single read FPitch write SetPitch default 1.0; |
| Published | property Priority: Single read FPriority write SetPriority default 0.5; |
| Published | property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance
default DefaultReferenceDistance; |
| Published | property MaxDistance: Single read FMaxDistance write SetMaxDistance
default DefaultMaxDistance; |
Description
Constants
| Public | DefaultReferenceDistance = 1.0; |
|
This item has no description. | |
| Public | DefaultMaxDistance = 10000.0; |
|
This item has no description. | |
Methods
| Protected | function GetInternalText: String; virtual; |
|
This item is declared in ancestor TCastleComponent. This item has no description. | |
| Protected | procedure SetInternalText(const Value: String); virtual; |
|
This item is declared in ancestor TCastleComponent. This item has no description. | |
| Protected | procedure SetName(const Value: TComponentName); override; |
|
This item is declared in ancestor TCastleComponent. This item has no description. | |
| Protected | procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual; |
|
This item is declared in ancestor TCastleComponent. Enumerate all properties that are possible to translate in this component. E.g. in TCastleLabel it will return TCastleLabel.Caption, in TCastleEdit it will return TCastleEdit.Text and TCastleEdit.Placeholder. Returns only non-empty properties, thus assuming that if current (by convention, English) text is empty, then there is no point in translating it. Moreover descendants may define boolean properties to exclude particular text from translating, e.g. TCastleLabel.CaptionTranslate, TCastleEdit.TextTranslate, TCastleEdit.PlaceholderTranslate. It is not recursive (it doesn't enumerate children properties). Use global TranslateProperties procedure to call this on a hierarchy of TComponent. You usually don't want to call this method (it is called by other engine routines). But you may find it useful to override this, if you define new component. | |
| Public | procedure CustomSerialization(const SerializationProcess: TSerializationProcess); virtual; |
|
This item is declared in ancestor TCastleComponent. Override this method to call various methods of SerializationProcess, which in turn allows to serialize/deserialize things that are not published. This allows to serialize/deserialize with more freedom, e.g. to serialize/deserialize some private field. | |
| Public | procedure SetTransient; |
|
This item is declared in ancestor TCastleComponent. Ignore this component when serializing parent's TCastleUserInterface.Controls list or TCastleTransform.List, and do not show this component in CGE editor. This simply sets csTransient flag in ComponentStyle. This is useful for children that are automatically managed by the parent, and should not be modified by user code. For example, TCastleCheckbox is internally composed from TCastleImageControl and TCastleLabel children, but we don't want to serialize or even show these children to user. Note that if you want to prevent this component from serializing as part of TCastleUserInterface.Controls list or TCastleTransform.List, but you still want it to be visible in CGE editor, then make it a "subcomponent" instead, by Note that both csSubComponent and csTransient only disable the component serialization as part of parent's lists enumerated by CustomSerialization (see internal TCastleUserInterface.SerializeChildrenEnumerate , TCastleTransform.SerializeChildrenEnumerate, TCastleTransform.SerializeBehaviorsEnumerate). If you will make the component published in its own property (which is normal for "subcomponents") then it will be serialized anyway, just as part of it's own property (like TCastleScrollView.ScrollArea). So to really avoid serializing a children component make it csSubComponent and/or csTransient, and do not publish it. | |
| Public | procedure AddNonVisualComponent(const NonVisualComponent: TComponent); |
|
This item is declared in ancestor TCastleComponent. Add non-visual component to this component. This is used to organize non-visual components in a tree hierarchy, in CGE designs and editor.
See also
| |
| Public | procedure InsertNonVisualComponent(const Index: Integer; const NonVisualComponent: TComponent); |
|
This item is declared in ancestor TCastleComponent. Insert non-visual component to this component. This is used to organize non-visual components in a tree hierarchy, in CGE designs and editor.
See also
| |
| Public | procedure RemoveNonVisualComponent(const NonVisualComponent: TComponent); |
|
This item is declared in ancestor TCastleComponent. Removes the component previously added by AddNonVisualComponent. | |
| Public | function NonVisualComponentsIndexOf(const NonVisualComponent: TComponent): Integer; |
|
This item is declared in ancestor TCastleComponent. Index of the previously added non-visual component. Returns -1 if the component was not found. | |
| Public | function NonVisualComponentsCount: Integer; |
|
This item is declared in ancestor TCastleComponent. Count of components added by AddNonVisualComponent.
See also
| |
| Public | function NonVisualComponentsEnumerate: TNonVisualComponentsEnumerator; |
|
This item is declared in ancestor TCastleComponent.
You can enumerate current non-visual components using loop like See also
| |
| Public | function ValueIsStreamed: Boolean; virtual; |
|
This item is declared in ancestor TCastleComponent.
Whether the current value of this object should be written to the stream. This should be This is used by CastleComponentSerialize, which is used in Castle Game Engine for all serialization. In simple cases, this just says whether the current value of this object equals to some default value. The default implementation of this class returns Descendants that override this to sometimes return The name of this method is consistent with TPropertyEditor.ValueIsStreamed in LCL. | |
| Public | procedure DesignerInfo(const SList: TStrings); virtual; |
|
This item is declared in ancestor TCastleComponent.
Override to add information that should be visible at design-time. Call | |
| Public | procedure DesignerWarnings(const SList: TStrings); virtual; |
|
This item is declared in ancestor TCastleComponent.
Override to add warnings that should be visible at design-time. Call | |
| Protected | procedure Loaded; override; |
|
This item has no description. | |
| Public | constructor Create(AOwner: TComponent); override; |
|
This item has no description. | |
| Public | destructor Destroy; override; |
|
This item has no description. | |
| Public | function PropertySections(const PropertyName: String): TPropertySections; override; |
|
This item has no description. Showing description inherited from TCastleComponent.PropertySections. Section where to show property in the editor. | |
| Public | procedure LoadFromStream(const AStream: TStream; const MimeType: String); |
|
Load sound contents from given TStream.
Parameters
| |
| Public | function Duration: Single; |
|
Duration of the sound, in seconds. -1 if not loaded yet. The sound is loaded once you set Url and don't get any loading exceptions. | |
| Public | function DataFormat: TSoundDataFormat; |
|
Sound data format (disregarding compression on top of it), for informational purposes. Undefined if not loaded yet. The sound is loaded once you set Url and don't get any loading exceptions. | |
| Public | function Frequency: Cardinal; |
|
Frequency (sample rate) of the loaded sound file. 0 if not loaded yet. The sound is loaded once you set Url and don't get any loading exceptions. | |
Properties
| Public | property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents; |
|
This item is declared in ancestor TCastleComponent. Components added by AddNonVisualComponent. | |
| Public | property IsLoading: Boolean read FIsLoading; |
|
This item is declared in ancestor TCastleComponent. Is the component during deserialization now. Note: We can't use | |
| Public | property MinGain: Single read FMinGain write SetMinGain default 0.0; platform; |
|
Warning: this symbol is specific to some platform. Force a minimum sound loudness, despite what volume would be calculated by the spatialization. This can be used to force sound to be audible, even when it's far away from the listener. It must be in [0, 1] range. By default it is 0. | |
| Public | property MaxGain: Single read FMaxGain write SetMaxGain default 1.0; platform; |
|
Warning: this symbol is specific to some platform. Force a maximum sound loudness, despite what volume would be calculated by the spatialization. This can be used to limit sound volume, regardless of the distance attenuation calculation. It must be in [0, 1] range. By default it is 1. | |
| Published | property Url: String read FUrl write SetUrl; |
|
URL of the sound file. Set this to load a new sound buffer, you can set to '' to clear the sound buffer. If you plan to change Stream, note that it is best to do it before setting Url. Changing Stream while Url is already set means that the sound is reloaded. | |
| Published | property Stream: Boolean read FStream write SetStream default false; |
|
Play sound using streaming. This means that the sound is gradually decompressed in memory, which means that loading time is much smaller, although there may be a small overhead on CPU during playback. Streaming is usually a good idea for longer sounds, e.g. music tracks. See also TSoundLoading for details. If you plan to change Stream, note that it is best to do it before setting Url. Changing Stream while Url is already set means that the sound is reloaded. | |
| Published | property Volume: Single read FVolume write SetVolume default 1.0; |
|
Volume (how loud the sound is). Use this to indicate that e.g. a plane engine is louder than a mouse squeak (when heard from the same distance). Note: Do not make the actual sound data (in sound files) louder/more silent to express that something is louder/more silent in reality. This would usually lower the sound quality. Instead, keep your sound file data at max loudness ("normalized"), and use this property to adjust the volume associated with the sound. The effective sound volume is a multiplication of TCastleSound.Volume, TCastlePlayingSound.Volume and TCastleSoundSource.Volume (if the sound is played through TCastleSoundSource). It is also affected by spatial calculations (if the sound is played through TCastleSoundSource with TCastleSoundSource.Spatial = Any value > 0 is allowed. The default is 1. Note that, while values > 1 are allowed, but some sound backends (like OpenAL) may clip the resulting sound volume (after all volume influences, including spatial calculations are done) to 1.0. | |
| Published | property Pitch: Single read FPitch write SetPitch default 1.0; |
|
Sound playing speed. The effective sound pitch is a multiplication of TCastleSound.Pitch, TCastlePlayingSound.Pitch and TCastleSoundSource.Pitch (if the sound is played through TCastleSoundSource). Changing this naturally also changes the audible sound. Each reduction by 50 percent equals a pitchshift of -12 semitones (one octave reduction). Each doubling equals a pitch shift of 12 semitones (one octave increase). Any value > 0 is allowed. | |
| Published | property Priority: Single read FPriority write SetPriority default 0.5; |
|
How important is the sound, between 0.0 (least important) to 1.0 (most important). The sound engine sometimes has to interrupt (or even not start at all) playback of some non-important sound, to have a good performance of audio mixing. In these cases, the sound with higher priority always "wins" over sound with lower priority. That is, sound with lower priority will be interrupted (the slot will be "stolen") to make room for sound with higher priority. Note: Many sound APIs (Unity, FMOD, Wwise, X3D...) have a similar property, with inconsistent range (minimum, maximum) and inconsistent meaning (some say "lower is more important", some say "higher is more important"). Our treatment of this property is similar to X3D, as it satisfies a number of important points: it defines easy to remember min/max (0 and 1), it is agnostic to the underlying precision (e.g. it has to map to 257 levels in FMOD, 100 levels in Wwise). Also, "higher is more important" seems just more natural. | |
| Published | property ReferenceDistance: Single read FReferenceDistance write SetReferenceDistance
default DefaultReferenceDistance; |
|
Spatial sound is fully audible (with Volume) at this distance. See TSoundDistanceModel for a description how distance affects the sound volume. | |
| Published | property MaxDistance: Single read FMaxDistance write SetMaxDistance
default DefaultMaxDistance; |
|
Distance at which sound volume stops attenuating. For the linear distance model (SoundEngine.DistanceModel = dmLinear) this is also a distance at which sound volume drops to zero (completely silent). See TSoundDistanceModel for a description how distance affects the sound volume. | |
Generated by PasDoc 0.17.0.snapshot.