SFXSource

Engine/source/sfx/sfxSource.h

Baseclass for sources and controllers.

More...

Fading

The fade system consists of "persistent" fades placed at the beginning and end of the playback range and of "temporary" fade segments placed in the playback range when stopping/pausing/resuming a source in midst of playback.

enum
FadeSegmentType {
  FadeSegmentNone 
  FadeSegmentPlay 
  FadeSegmentStop 
  FadeSegmentPause 
}

Type for temporary fade segments.

_setFadeTimes(F32 fadeInTime, F32 fadeOutTime)

Set up a temporary fade-out segment.

The current "persistent" fade-in time in seconds.

The current "persistent" fade-out time in seconds.

Playtime at which persistent fade-in ends. -1 if no fade-in.

Playtime at which persistent fade-out starts. -1 if no fade-out.

Type of the current temporary fade segment.

Easing curve for the current fade segment.

Playback position where the current temporary fade segment starts.

Playback position where the current temporary fade segment ends.

Fade time to apply when transitioning to mSavedStatus.

Status

_setStatus(SFXStatus newStatus)

Used internally for setting the sound status.

Update the playback status of the source.

Current playback status.

The playback status that the source actually wants to be in.

Console functions to call when the source status changes.

Datablocks

The track datablock is optional but the description datablock is required.

If either of the two goes away, the source will auto-delete itself.

These members are SimObjectPtr so that temporary track and description objects that are set to auto-delete will work.

The track being played by this source.

The description holding the SFX sound configuration.

Volume

_setVolume(F32 volume)

Set volume without affecting CustomVolumeFlag.

Update the effective volume of the source.

Returns the source volume at its unaltered initial setting, i.e.

setVolume(F32 volume)

Sets the source volume which will still be scaled by the master and group volumes.

Set the per-source volume scale factor.

Returns the volume with respect to the master and group volumes and the listener.

setFadeTimes(F32 fadeInTime, F32 fadeOutTime)

The desired sound volume.

Volume before fade stage.

"mVolume" after fade stage.

Volume scale factor imposed on this source by controller.

Effective volume after fade and modulation but before distance attenuation.

Effective volume after distance attenuation.

Virtualization

_setPriority(F32 priority)

Set priority without affecting CustomPriorityFlag.

Update the effective priority of the source.

Returns the source priority.

setPriority(F32 priority)

The desired sound priority.

The priority scale factor imposed by controllers.

The final priority level.

Pitch

_setPitch(F32 pitch)

Set pitch without affecting CustomPitchFlag.

Update the effective pitch of the source.

Returns the source pitch scale.

setPitch(F32 pitch)

Sets the source pitch scale.

The desired sound pitch.

The pitch scale factor imposed by controllers.

The final effective pitch.

3D Sound

Randomize transform based on scatter settings.

Set 3D min/max distance without affecting CustomRadiusFlag.

_setCone(F32 innerAngle, F32 outerAngle, F32 outerVolume)

Set 3D cone without affecting CustomConeFlag.

bool
is3d()

Returns true if this is a 3D source.

Returns the last set velocity.

Returns the last set transform.

setTransform(const MatrixF & transform)

Sets the position and orientation for a 3d buffer.

Sets the velocity for a 3d buffer.

Sets the minimum and maximum distances for 3d falloff.

setCone(F32 innerAngle, F32 outerAngle, F32 outerVolume)

Set sound cone of a 3D sound.

Returns the last distance to the listener.

The transform if this is a 3d source.

The last set velocity.

Distance at which to begin distanced-based volume attenuation.

Distance at which to stop distance-based volume attenuation.

Inside cone angle in degrees.

Outside cone angle in degrees.

Outside cone volume.

The distance of this source to the last listener position.

bool

If true, the transform position has been randomized.

Playback

Start playback.

Pause playback.

Stop playback.

The simulation tick count that playback was started at for this source.

Time object used to keep track of playback.

Modifiers

Delete all modifiers of the given type.

addMarker(const String & name, F32 pos)

List of modifiers that are active on this source.

Callbacks

DECLARE_CALLBACK(void , onStatusChange , (SFXStatus newStatus) )
DECLARE_CALLBACK(void , onParameterValueChange , (SFXParameter *parameter) )

Playback Status

Returns the last known status without doing an update.

Return the status that the source wants to be in.

Returns the sound status.

bool

Returns true if the source is playing.

bool

Returns true if the source is stopped.

bool

Returns true if the source has been paused.

bool

Returns true if the source is currently being virtualized.

bool

Returns true if this is a looping source.

Playback Control

play(F32 fadeInTime)

Starts the sound from the current playback position.

stop(F32 fadeOutTime)

Stops playback and resets the playback position.

pause(F32 fadeOutTime)

Pauses the sound playback.

Return the elapsed play time of the current loop cycle so far in seconds.

Return the total elapsed play time so far in seconds.

Return the total play time of the source in seconds.

Dynamic Parameters

Dynamic parameters allow to pass on values from the game system to the sound system and thus implement interactive audio.

It is dependent on the back-end source implementation how it will react to parameter settings.

Change Notifications

Notify the source that its attached SFXDescription has changed.

Notify the source that its attached SFXTrack has changed.

Protected Types

enum
Flags {
  CustomVolumeFlag = BIT( 0 )
  CustomPitchFlag = BIT( 1 )
  CustomPriorityFlag = BIT( 2 )
  CustomRadiusFlag = BIT( 3 )
  CustomConeFlag = BIT( 4 )
  CustomFadeFlag = BIT( 5 )
  CustomGroupFlag = BIT( 6 )
}
ModifierList 

Public Types

Parent 

Public Friends

class

Protected Attributes

Protected Functions

SFXSource(SFXTrack * track, SFXDescription * description)
bool

We overload this to disable creation of a source via script 'new'.

Protected Static Functions

const char *
_getDescription(void * obj, const char * data)
bool
_setDescription(void * obj, const char * index, const char * data)

Public Functions

bool
DECLARE_DESCRIPTION("SFX sound playback controller." )

Return the SFX description associated with this source. Never NULL.

Return the source group that this source has been assigned to.

Returns the track played by this source; NULL for sources playing directly from streams.

bool

Called when the object is added to the sim.

Called when a SimObject is deleted.

Called when the object is added to a SimGroup.

Called when the object is removed from the sim.

Public Static Functions

Detailed Description

Baseclass for sources and controllers.

Fading

The fade system consists of "persistent" fades placed at the beginning and end of the playback range and of "temporary" fade segments placed in the playback range when stopping/pausing/resuming a source in midst of playback.

FadeSegmentType

Enumerator

FadeSegmentNone

No temporary fade segment set.

FadeSegmentPlay

Temporary fade-in segment.

FadeSegmentStop

Temporary fade-out segment ending in stop().

FadeSegmentPause

Temporary fade-out segment ending in pause().

Type for temporary fade segments.

_setFadeTimes(F32 fadeInTime, F32 fadeOutTime)

Reimplemented by: SFXFMODEventSource

_setupFadeOutSegment(FadeSegmentType type, F32 fadeOutTime)

Set up a temporary fade-out segment.

F32 mFadeInTime 

The current "persistent" fade-in time in seconds.

Taken initially from the SFXDescription and as long as not being manually set on the source, will stay with the description's "fadeInTime" property.

F32 mFadeOutTime 

The current "persistent" fade-out time in seconds.

Taken initially from the SFXDescription and as long as not being manually set on the source, will stay with the description's "fadeOutTime" property.

F32 mFadeInPoint 

Playtime at which persistent fade-in ends. -1 if no fade-in.

F32 mFadeOutPoint 

Playtime at which persistent fade-out starts. -1 if no fade-out.

FadeSegmentType mFadeSegmentType 

Type of the current temporary fade segment.

No temporary fade segment is in place when this is FadeSegmentNone.

EaseF * mFadeSegmentEase 

Easing curve for the current fade segment.

F32 mFadeSegmentStartPoint 

Playback position where the current temporary fade segment starts.

F32 mFadeSegmentEndPoint 

Playback position where the current temporary fade segment ends.

F32 mSavedFadeTime 

Fade time to apply when transitioning to mSavedStatus.

Status

_setStatus(SFXStatus newStatus)

Used internally for setting the sound status.

_updateStatus()

Update the playback status of the source.

Meant for subclasses that need to poll a connected resource.

Reimplemented by: SFXFMODEventSource, SFXSound

SFXStatus mStatus 

Current playback status.

SFXStatus mSavedStatus 

The playback status that the source actually wants to be in.

StringTableEntry mStatusCallback 

Console functions to call when the source status changes.

If not set, "onStatusChange" will be called on the source object.

Datablocks

The track datablock is optional but the description datablock is required.

If either of the two goes away, the source will auto-delete itself.

These members are SimObjectPtr so that temporary track and description objects that are set to auto-delete will work.

SimObjectPtr< SFXTrack > mTrack 

The track being played by this source.

note:

Will be null for sources that have been created from SFXStreams.

SimObjectPtr< SFXDescription > mDescription 

The description holding the SFX sound configuration.

Volume

_setVolume(F32 volume)

Set volume without affecting CustomVolumeFlag.

_updateVolume(const MatrixF & listener)

Update the effective volume of the source.

Reimplemented by: SFXFMODEventSource, SFXController, SFXSound

getVolume()

Returns the source volume at its unaltered initial setting, i.e.

prior to fading, modulation, and attenuation.

setVolume(F32 volume)

Sets the source volume which will still be scaled by the master and group volumes.

note:

Note that if you set an explicit volume on a source

getModulativeVolume()

setModulativeVolume(F32 value)

Set the per-source volume scale factor.

getPreAttenuatedVolume()

getAttenuatedVolume()

Returns the volume with respect to the master and group volumes and the listener.

getFadeInTime()

getFadeOutTime()

setFadeTimes(F32 fadeInTime, F32 fadeOutTime)

F32 mVolume 

The desired sound volume.

F32 mPreFadeVolume 

Volume before fade stage.

Used as input to volume computation. Usually this corresponds to mVolume but when fading out from an already faded start volume, this contains the starting mFadedVolume.

F32 mFadedVolume 

"mVolume" after fade stage.

Same as "mPreFadeVolume" if no fade is active.

F32 mModulativeVolume 

Volume scale factor imposed on this source by controller.

F32 mPreAttenuatedVolume 

Effective volume after fade and modulation but before distance attenuation.

For non-3D sounds, this is the final effective volume.

F32 mAttenuatedVolume 

Effective volume after distance attenuation.

Continuously updated to match listener position. For non-3D sounds, this is the same as mPreAttenuatedVolume.

note:

The distance attenuation that is computed here does not take sound cones into account so the computed attenuated volume may be higher than the actual effective volume on the device (never lower though).

Virtualization

_setPriority(F32 priority)

Set priority without affecting CustomPriorityFlag.

_updatePriority()

Update the effective priority of the source.

Reimplemented by: SFXFMODEventSource, SFXController, SFXSound

getPriority()

Returns the source priority.

setPriority(F32 priority)

getModulativePriority()

setModulativePriority(F32 value)

getEffectivePriority()

F32 mPriority 

The desired sound priority.

F32 mModulativePriority 

The priority scale factor imposed by controllers.

F32 mEffectivePriority 

The final priority level.

Pitch

_setPitch(F32 pitch)

Set pitch without affecting CustomPitchFlag.

_updatePitch()

Update the effective pitch of the source.

Reimplemented by: SFXFMODEventSource, SFXController, SFXSound

getPitch()

Returns the source pitch scale.

setPitch(F32 pitch)

Sets the source pitch scale.

getModulativePitch()

setModulativePitch(F32 value)

getEffectivePitch()

F32 mPitch 

The desired sound pitch.

F32 mModulativePitch 

The pitch scale factor imposed by controllers.

F32 mEffectivePitch 

The final effective pitch.

3D Sound

_scatterTransform()

Randomize transform based on scatter settings.

_setMinMaxDistance(F32 min, F32 max)

Set 3D min/max distance without affecting CustomRadiusFlag.

Reimplemented by: SFXFMODEventSource, SFXSound

_setCone(F32 innerAngle, F32 outerAngle, F32 outerVolume)

Set 3D cone without affecting CustomConeFlag.

Reimplemented by: SFXFMODEventSource, SFXSound

is3d()

Returns true if this is a 3D source.

getVelocity()

Returns the last set velocity.

getTransform()

Returns the last set transform.

setTransform(const MatrixF & transform)

Sets the position and orientation for a 3d buffer.

Reimplemented by: SFXFMODEventSource, SFXSound

setVelocity(const VectorF & velocity)

Sets the velocity for a 3d buffer.

Reimplemented by: SFXFMODEventSource, SFXSound

setMinMaxDistance(F32 min, F32 max)

Sets the minimum and maximum distances for 3d falloff.

setCone(F32 innerAngle, F32 outerAngle, F32 outerVolume)

Set sound cone of a 3D sound.

Parameters:

innerAngle

Inner cone angle in degrees.

outerAngle

Outer cone angle in degrees.

outerVolume

Outer volume factor.

getDistToListener()

Returns the last distance to the listener.

note:

Only works when distance attenuation calculations are being triggered by SFX and are not left exclusively to the SFX device.

MatrixF mTransform 

The transform if this is a 3d source.

VectorF mVelocity 

The last set velocity.

F32 mMinDistance 

Distance at which to begin distanced-based volume attenuation.

F32 mMaxDistance 

Distance at which to stop distance-based volume attenuation.

F32 mConeInsideAngle 

Inside cone angle in degrees.

F32 mConeOutsideAngle 

Outside cone angle in degrees.

F32 mConeOutsideVolume 

Outside cone volume.

F32 mDistToListener 

The distance of this source to the last listener position.

bool mTransformScattered 

If true, the transform position has been randomized.

Parameters

_addParameter(StringTableEntry name)

_onParameterEvent(SFXParameter * parameter, SFXParameterEvent event)

Reimplemented by: SFXFMODEventSource, SFXController, SFXSound

Vector< SFXParameter * > mParameters 

Playback

_play()

Start playback.

For implementation by concrete subclasses.

note:

This method should not take fading into account.

Reimplemented by: SFXController, SFXSound

_pause()

Pause playback.

For implementation by concrete subclasses.

note:

This method should not take fading into account.

Reimplemented by: SFXController, SFXSound

_stop()

Stop playback.

For implementation by concrete subclasses.

note:

This method should not take fading into account.

Reimplemented by: SFXController, SFXSound

U32 mPlayStartTick 

The simulation tick count that playback was started at for this source.

TimeSource mPlayTimer 

Time object used to keep track of playback.

Modifiers

_clearModifiers()

Delete all modifiers of the given type.

addModifier(SFXModifier * modifier)

addMarker(const String & name, F32 pos)

ModifierList mModifiers 

List of modifiers that are active on this source.

Callbacks

DECLARE_CALLBACK(void , onStatusChange , (SFXStatus newStatus) )

DECLARE_CALLBACK(void , onParameterValueChange , (SFXParameter *parameter) )

Playback Status

getLastStatus()

Returns the last known status without doing an update.

getSavedStatus()

Return the status that the source wants to be in.

Used for playback control in combination with source groups.

getStatus()

Returns the sound status.

isPlaying()

Returns true if the source is playing.

isStopped()

Returns true if the source is stopped.

isPaused()

Returns true if the source has been paused.

isVirtualized()

Returns true if the source is currently being virtualized.

Reimplemented by: SFXSound

isLooping()

Returns true if this is a looping source.

Playback Control

play(F32 fadeInTime)

Starts the sound from the current playback position.

Parameters:

fadeInTime

Seconds for sound to fade in. If -1, fadeInTime from SFXDescription is used. Note that certain SFXSource classes may not support values other than 0 and -1.

Reimplemented by: SFXFMODEventSource

stop(F32 fadeOutTime)

Stops playback and resets the playback position.

note:

This method is also required to release all playback-related resources on the device.

Parameters:
fadeOutTime

Seconds for sound to fade out. If -1, fadeOutTime from SFXDescription is used. Note that certain SFXSource classes may not support values other than 0 and -1.

Reimplemented by: SFXFMODEventSource

pause(F32 fadeOutTime)

Pauses the sound playback.

Parameters:

fadeOutTime

Seconds for sound to fade out. If -1, fadeOutTime from SFXDescription is used. Note that certain SFXSource clsases may not support values other than 0 and -1.

Reimplemented by: SFXFMODEventSource

getElapsedPlayTimeCurrentCycle()

Return the elapsed play time of the current loop cycle so far in seconds.

Reimplemented by: SFXSound

getElapsedPlayTime()

Return the total elapsed play time so far in seconds.

getTotalPlayTime()

Return the total play time of the source in seconds.

Positive infinity by default.

note:

For looping sounds, this must include only the playtime of a single cycle.

Reimplemented by: SFXSound

Dynamic Parameters

Dynamic parameters allow to pass on values from the game system to the sound system and thus implement interactive audio.

It is dependent on the back-end source implementation how it will react to parameter settings.

getNumParameters()

getParameter(U32 index)

addParameter(SFXParameter * parameter)

removeParameter(SFXParameter * parameter)

Change Notifications

notifyDescriptionChanged()

Notify the source that its attached SFXDescription has changed.

notifyTrackChanged()

Notify the source that its attached SFXTrack has changed.

Protected Types

Flags

Enumerator

CustomVolumeFlag = BIT( 0 )
CustomPitchFlag = BIT( 1 )
CustomPriorityFlag = BIT( 2 )
CustomRadiusFlag = BIT( 3 )
CustomConeFlag = BIT( 4 )
CustomFadeFlag = BIT( 5 )
CustomGroupFlag = BIT( 6 )
typedef Torque::List< SFXModifier * > ModifierList 
typedef GenericTimeSource< RealMSTimer > TimeSource 

Public Types

typedef SimGroup Parent 

Public Friends

Protected Attributes

BitSet32 mFlags 

Protected Functions

SFXSource(SFXTrack * track, SFXDescription * description)

_update()

Reimplemented by: SFXController

processArguments(S32 argc, ConsoleValueRef * argv)

Reimplemented from: SimGroup

Protected Static Functions

_getDescription(void * obj, const char * data)

_setDescription(void * obj, const char * index, const char * data)

Public Functions

SFXSource()

~SFXSource()

acceptsAsChild(SimObject * object)

DECLARE_CATEGORY("SFX" )

DECLARE_CONOBJECT(SFXSource )

DECLARE_DESCRIPTION("SFX sound playback controller." )

getDescription()

Return the SFX description associated with this source. Never NULL.

getSourceGroup()

Return the source group that this source has been assigned to.

getTrack()

Returns the track played by this source; NULL for sources playing directly from streams.

onAdd()

Reimplemented from: SimObject

onDeleteNotify(SimObject * object)

Reimplemented from: SimSet

Reimplemented by: SFXSound

onGroupAdd()

Reimplemented from: SimObject

onRemove()

Reimplemented from: SimGroup

Reimplemented by: SFXSound

update()

Public Static Functions

initPersistFields()