Class TCastleSoundSource

Description
Hierarchy
Methods
Properties

Unit

CastleBehaviors

Declaration

type TCastleSoundSource = class(TCastleBehavior)

Description

Behavior to play spatial sounds, that automatically follow the parent TCastleTransform transformation. Multiple such behaviors may be attached to a single TCastleTransform (if you need to play multiple looping sounds, or want to have multiple playback settings like different Volume control).

Source: transform/castlebehaviors_soundsource.inc (line 82).

Hierarchy

Show Additional Members:

Overview

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 BeforeRender( const CameraView: TViewVectors; const ParentParentWorldTransformation: TTransformation); virtual;
Protected procedure ParentChanged; virtual; deprecated 'Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach';
Protected procedure WorldAfterAttach; virtual;
Protected procedure WorldBeforeDetach; virtual;
Protected function CanAttachToParent(const NewParent: TCastleTransform; out ReasonWhyCannot: String): Boolean; virtual;
Public procedure BeforeDestruction; override;
Public function World: TCastleAbstractRootTransform;
Protected procedure ParentAfterAttach; override;
Protected procedure ParentBeforeDetach; override;
Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure Play(const ASound: TCastleSound); overload;
Public procedure Play(const PlayingSound: TCastlePlayingSoundSource); overload;

Properties

Public property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;
Public property IsLoading: Boolean read FIsLoading;
Public property Parent: TCastleTransform read FParent;
Public property ListenWorldChange: Boolean read FListenWorldChange write SetListenWorldChange;
Published property Sound: TCastleSound read FSound write SetSound;
Published property SoundPlaying: Boolean read FSoundPlaying write SetSoundPlaying default true;
Published property Spatial: Boolean read FSpatial write SetSpatial default true;
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 1.0;

Description

Methods

Protected function GetInternalText: String; virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 575).

Protected procedure SetInternalText(const Value: String); virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 576).

Protected procedure SetName(const Value: TComponentName); override;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 577).

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.

Source: base/castleclassutils.pas (line 598).

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.

Source: base/castleclassutils.pas (line 610).

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 SetSubComponent(true).

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.

Source: base/castleclassutils.pas (line 663).

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
NonVisualComponentsCount
Count of components added by AddNonVisualComponent.
NonVisualComponents
Components added by AddNonVisualComponent.
NonVisualComponentsEnumerate
You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do ....

Source: base/castleclassutils.pas (line 672).

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
NonVisualComponentsCount
Count of components added by AddNonVisualComponent.
NonVisualComponents
Components added by AddNonVisualComponent.
NonVisualComponentsEnumerate
You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do ....

Source: base/castleclassutils.pas (line 681).

Public procedure RemoveNonVisualComponent(const NonVisualComponent: TComponent);

This item is declared in ancestor TCastleComponent.

Removes the component previously added by AddNonVisualComponent.

Source: base/castleclassutils.pas (line 684).

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.

Source: base/castleclassutils.pas (line 688).

Public function NonVisualComponentsCount: Integer;

This item is declared in ancestor TCastleComponent.

Count of components added by AddNonVisualComponent.

See also
AddNonVisualComponent
Add non-visual component to this component.
NonVisualComponents
Components added by AddNonVisualComponent.
NonVisualComponentsEnumerate
You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do ....

Source: base/castleclassutils.pas (line 695).

Public function NonVisualComponentsEnumerate: TNonVisualComponentsEnumerator;

This item is declared in ancestor TCastleComponent.

You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do .... Do not call this method in other contexts, it is only useful for "for..in" construction.

See also
AddNonVisualComponent
Add non-visual component to this component.

Source: base/castleclassutils.pas (line 705).

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 True if anything inside this object should be serialized (which means it has non-default value or "stored" specifier indicates that it should be serialized).

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 True (so always write).

Descendants that override this to sometimes return False (so no need to write) must be very careful: any addition of a new field requires extending this method, otherwise new field may not be saved sometimes (when all other fields are default). Descentants of such classes must also be aware of it. This check must include everything that is inside this object in JSON, including subcomponents and children objects (as done e.g. by TSerializationProcess.ReadWriteList). In practice, overriding this method is only reasonable for simple classes that will not change much in the future, like TCastleVector3Persistent.

The name of this method is consistent with TPropertyEditor.ValueIsStreamed in LCL.

Source: base/castleclassutils.pas (line 739).

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 SList.Add for each new line of information.

Source: base/castleclassutils.pas (line 743).

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 SList.Add for each new warning.

Source: base/castleclassutils.pas (line 747).

Protected procedure BeforeRender( const CameraView: TViewVectors; const ParentParentWorldTransformation: TTransformation); virtual;

This item is declared in ancestor TCastleBehavior.

Event called right before rendering the parent TCastleTransform. Override this if you have to adjust the parent transformation strictly before the rendering.

Compared to adjusting the parent transformation in e.g. Update, adjusting the parent transformation here has advantages:

  1. There's no 1-frame delay between moving the thing that causes the change (like camera) and updating the thing that reacts to it (like a transformation with a billboard).

  2. We adjust transformation before rendering each occurrence of TCastleTransform in the viewport tree. This matters if given TCastleTransform may occur multiple times in the viewport tree, directly or through TCastleTransformReference.

  3. We adjust transformation before each render, so things are OK if given TCastleTransform is present in multiple viewports (see https://castle-engine.io/multiple_viewports_to_display_one_world).

For example, adjusting the TCastleTransform done by the TCastleBillboard is done using this method. The transformation in this case is determined by the camera and parent's parent transformation. The transformation has to be applied without any delay (even a 1-frame delay would be visible, as artifacts caused by billboard not perfectly aligned with the camera would be visible – blending sort along camera direction in sort3D is not perfect if billboard doesn't exactly match camera direction). And the transformation with billboard may be present in multiple viewports and/or multiple times in the same viewport tree.

Parameters
CameraView
Current camera vectors, in world coordinates, used to render the scene now.
ParentParentWorldTransformation

World transformation of the parent of the parent of this behavior. The name is kind of convoluted, but consistent: When the parent of this behavior has exactly one parent TCastleTransform (not zero, not more) then ParentParentWorldTransformation.Transform is equivalent to Parent.Parent.WorldTransform.

Source: transform/castletransform_behavior.inc (line 103).

Protected procedure ParentChanged; virtual; deprecated 'Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach';

This item is declared in ancestor TCastleBehavior.

Warning: this symbol is deprecated: Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach

Called after Parent changed, at the end of TCastleTransform.AddBehavior, TCastleTransform.RemoveBehavior.

Source: transform/castletransform_behavior.inc (line 109).

Protected procedure WorldAfterAttach; virtual;

This item is declared in ancestor TCastleBehavior.

Called after Parent became part of World. Called only if ListenWorldChange is True.

Source: transform/castletransform_behavior.inc (line 126).

Protected procedure WorldBeforeDetach; virtual;

This item is declared in ancestor TCastleBehavior.

Called before Parent stops being part of World. Called only if ListenWorldChange is True.

This is also called at the destruction of behavior (more precisely from BeforeDestruction now). Even in this case, we guarantee that Parent is still valid during this call, and not in half-destroyed state. Before the actual destructor of TCastleBehavior we do BeforeParentDetach and BeforeWorldDetach and set Parent to Nil.

Source: transform/castletransform_behavior.inc (line 136).

Protected function CanAttachToParent(const NewParent: TCastleTransform; out ReasonWhyCannot: String): Boolean; virtual;

This item is declared in ancestor TCastleBehavior.

Check can this behavior be added to NewParent. When this returns False, it has to set also ReasonWhyCannot. When overriding this, you can use e.g. this code to make sure we are the only behavior of given class: 

function TCastleBillboard.CanAttachToParent(const NewParent: TCastleTransform;
  out ReasonWhyCannot: String): Boolean;
begin
  Result := inherited;
  if not Result then Exit;

  if NewParent.FindBehavior(TCastleBillboard) <> nil then
  begin
    ReasonWhyCannot := 'Only one TCastleBillboard behavior can be added to a given TCastleTransform';
    Result := false;
  end;
end;

Source: transform/castletransform_behavior.inc (line 158).

Public procedure BeforeDestruction; override;

This item is declared in ancestor TCastleBehavior.

This item has no description.

Source: transform/castletransform_behavior.inc (line 161).

Public function World: TCastleAbstractRootTransform;

This item is declared in ancestor TCastleBehavior.

Reference to the root transformation (typically matching the TCastleViewport.Items value) corresponding to the parent of this behavior.

May be Nil if the behavior is not yet added to the parent TCastleTransform, or when the TCastleTransform is not yet part of the TCastleAbstractRootTransform (which means that TCastleTransform is not added to the viewport yet). You can use ListenWorldChange and override WorldBeforeDetach, WorldAfterAttach to be notified when this changes.

Source: transform/castletransform_behavior.inc (line 184).

Protected procedure ParentAfterAttach; override;

This item has no description. Showing description inherited from TCastleBehavior.ParentAfterAttach.

Called after Parent changed, e.g. at the end of TCastleTransform.AddBehavior.

Source: transform/castlebehaviors_soundsource.inc (line 111).

Protected procedure ParentBeforeDetach; override;

This item has no description. Showing description inherited from TCastleBehavior.ParentBeforeDetach.

Called before Parent changed, e.g. at the beginning of TCastleTransform.RemoveBehavior.

This is also called at the destruction of behavior (more precisely from BeforeDestruction now). Even in this case, we guarantee that Parent is still valid during this call, and not in half-destroyed state. Before the actual destructor of TCastleBehavior we do BeforeParentDetach and BeforeWorldDetach and set Parent to Nil.

Source: transform/castlebehaviors_soundsource.inc (line 112).

Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;

This item has no description.

Source: transform/castlebehaviors_soundsource.inc (line 113).

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Source: transform/castlebehaviors_soundsource.inc (line 115).

Public destructor Destroy; override;

This item has no description.

Source: transform/castlebehaviors_soundsource.inc (line 116).

Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;

This item has no description. Showing description inherited from TCastleBehavior.Update.

Continuously occuring event, for various tasks.

Source: transform/castlebehaviors_soundsource.inc (line 117).

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.

Source: transform/castlebehaviors_soundsource.inc (line 118).

Public procedure Play(const ASound: TCastleSound); overload;

Play given sound once (not looping). If the sound source is spatial (TCastleSoundSource.Spatial), it's 3D position will reflect the Parent (TCastleTransform) position.

Source: transform/castlebehaviors_soundsource.inc (line 123).

Public procedure Play(const PlayingSound: TCastlePlayingSoundSource); overload;

Play given sound. If the sound source is spatial (TCastleSoundSource.Spatial), it's 3D position will reflect the Parent (TCastleTransform) position.

Set TCastlePlayingSound.Sound before passing it to this method. Otherwise, if TCastlePlayingSound.Sound is left Nil, nothing will be played.

Use the TCastlePlayingSound properties to provide additional information about the sound playback. E.g. assign TCastlePlayingSound.Loop TCastlePlayingSound.OnStop or control sound afterwards by TCastlePlayingSound.Stop, TCastlePlayingSound.Offset.

Consider using TCastlePlayingSound.FreeOnStop if you don't want to manage the lifetime of the TCastlePlayingSound instance.

Source: transform/castlebehaviors_soundsource.inc (line 140).

Properties

Public property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;

This item is declared in ancestor TCastleComponent.

Components added by AddNonVisualComponent.

Source: base/castleclassutils.pas (line 698).

Public property IsLoading: Boolean read FIsLoading;

This item is declared in ancestor TCastleComponent.

Is the component during deserialization now.

Note: We can't use csLoading in ComponentState because in Delphi it is not possible to control it from CastleComponentSerialize.

Source: base/castleclassutils.pas (line 711).

Public property Parent: TCastleTransform read FParent;

This item is declared in ancestor TCastleBehavior.

Parent TCastleTransform of this behavior. Change it by doing TCastleTransform.AddBehavior, TCastleTransform.RemoveBehavior.

Nil if this behavior is not yet added to a parent.

Source: transform/castletransform_behavior.inc (line 191).

Public property ListenWorldChange: Boolean read FListenWorldChange write SetListenWorldChange;

This item is declared in ancestor TCastleBehavior.

Set this to True to receive WorldBeforeDetach, WorldAfterAttach calls.

Source: transform/castletransform_behavior.inc (line 194).

Published property Sound: TCastleSound read FSound write SetSound;

Sound to play, always looping. Control playback of it using SoundPlaying.

Note that this is not the only sound possible to play using this TCastleSoundSource. You can play any other TCastleSound or TCastlePlayingSoundSource instance (looping or not looping) by calling Play method.

Source: transform/castlebehaviors_soundsource.inc (line 149).

Published property SoundPlaying: Boolean read FSoundPlaying write SetSoundPlaying default true;

Is the Sound currently playing. Setting it to False and back to True will restart playing sound from the beginning.

Source: transform/castlebehaviors_soundsource.inc (line 153).

Published property Spatial: Boolean read FSpatial write SetSpatial default true;

Is the sound playback spatialized. Affects sounds played by assigning Sound or calling Play here.

Spatial sounds are louder/more silent depending on their 3D distance to listener (this means a distance from TCastleTransform origin to the camera within the TCastleViewport). And their relative position to the listener in 3D is reflected by making them louder/more silent in the proper (e.g. left or right) speaker.

Note that some sound backends (like OpenAL) can only spatialize mono sounds, and play stereo sounds always as non-spatialized.

Source: transform/castlebehaviors_soundsource.inc (line 166).

Published property Volume: Single read FVolume write SetVolume default 1.0;

Volume (how loud the playing sound is).

The effective sound volume is a multiplication of TCastleSound.Volume, TCastlePlayingSound.Volume and TCastleSoundSource.Volume. It is also affected by spatial calculations (if the sound is played with TCastleSoundSource.Spatial = True) and finally by a master SoundEngine.Volume.

Any value > 0 is allowed.

Source: transform/castlebehaviors_soundsource.inc (line 177).

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.

Any value > 0 is allowed.

Source: transform/castlebehaviors_soundsource.inc (line 186).

Published property Priority: Single read FPriority write SetPriority default 1.0;

How important is the sound, between 0.0 (least important) to 1.0 (most important).

The effective priority is a multiplication of TCastleSound.Priority, TCastlePlayingSound.Priority and TCastleSoundSource.Priority.

Any value > 0 is allowed.

Source: transform/castlebehaviors_soundsource.inc (line 195).

Generated by PasDoc 0.17.0.snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.