SFXSource
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 { FadeSegmentNone FadeSegmentPlay FadeSegmentStop FadeSegmentPause }
Type for temporary fade segments.
_setFadeTimes(F32 fadeInTime, F32 fadeOutTime)
_setupFadeOutSegment(FadeSegmentType type, 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.
EaseF *
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.
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.
_updateVolume(const MatrixF & listener)
Update the effective volume of the source.
setModulativeVolume(F32 value)
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)
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)
setModulativePriority(F32 value)
The priority scale factor imposed by controllers.
The final priority level.
Pitch
Update the effective pitch of the source.
setModulativePitch(F32 value)
The pitch scale factor imposed by controllers.
The final effective pitch.
3D Sound
Randomize transform based on scatter settings.
_setMinMaxDistance(F32 min, F32 max)
Set 3D min/max distance without affecting CustomRadiusFlag.
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.
setVelocity(const VectorF & velocity)
Sets the velocity for a 3d buffer.
setMinMaxDistance(F32 min, F32 max)
Sets the minimum and maximum distances for 3d falloff.
Returns the last distance to the listener.
The transform if this is a 3d source.
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.
Parameters
_onParameterEvent(SFXParameter * parameter, SFXParameterEvent event)
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.
addModifier(SFXModifier * modifier)
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.
bool
Returns true if the source is playing.
bool
Returns true if the source is stopped.
bool
isPaused()
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
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.
getParameter(U32 index)
addParameter(SFXParameter * parameter)
removeParameter(SFXParameter * parameter)
Change Notifications
Notify the source that its attached SFXDescription has changed.
Notify the source that its attached SFXTrack has changed.
Protected Types
Flags { CustomVolumeFlag = BIT( 0 ) CustomPitchFlag = BIT( 1 ) CustomPriorityFlag = BIT( 2 ) CustomRadiusFlag = BIT( 3 ) CustomConeFlag = BIT( 4 ) CustomFadeFlag = BIT( 5 ) CustomGroupFlag = BIT( 6 ) }
Torque::List< SFXModifier * >
ModifierList
TimeSource
Public Types
Parent
Public Friends
class
Protected Functions
SFXSource(SFXTrack * track, SFXDescription * description)
bool
processArguments(S32 argc, ConsoleValueRef * argv)
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
acceptsAsChild(SimObject * object)
DECLARE_CATEGORY("SFX" )
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.
SFXTrack *
getTrack()
Returns the track played by this source; NULL for sources playing directly from streams.
bool
onAdd()
Called when the object is added to the sim.
onDeleteNotify(SimObject * object)
Called when a SimObject is deleted.
Called when the object is added to a SimGroup.
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:Parameters:This method is also required to release all playback-related resources on the device.
| 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()