Main   Class List   Namespace List   Wiki

SFXSource Class Reference
[Sound]

Playback controller for a sound source. More...

Inheritance diagram for SFXSource:
Inheritance graph
[legend]

List of all members.

Public Member Functions

void addMarker (String name, float pos)
 Add a notification marker called name at pos seconds of playback.
void addParameter (SFXParameter parameter)
 Attach parameter to the source,.
float getAttenuatedVolume ()
 Get the final effective volume level of the source.
float getFadeInTime ()
 Get the fade-in time set on the source.
float getFadeOutTime ()
 Get the fade-out time set on the source.
SFXParameter getParameter (int index)
 Get the parameter at the given index.
int getParameterCount ()
 Get the number of SFXParameters that are attached to the source.
float getPitch ()
 Get the pitch scale of the source.
SFXStatus getStatus ()
 Get the current playback status.
float getVolume ()
 Get the current base volume level of the source.
bool isPaused ()
 Test whether the source is currently paused.
bool isPlaying ()
 Test whether the source is currently playing.
bool isStopped ()
 Test whether the source is currently stopped.
void pause (float fadeOutTime=-1.f)
 Pause playback of the source.
void removeParameter (SFXParameter parameter)
 Detach parameter from the source.
void setCone (float innerAngle, float outerAngle, float outsideVolume)
 Set up the 3D volume cone for the source.
void setFadeTimes (float fadeInTime, float fadeOutTime)
 Set the fade time parameters of the source.
void setPitch (float pitch)
 Set the pitch scale of the source.
void setTransform (Point3F position, Point3F direction) void setTransform(Point3F position) void play(float fadeInTime
 Start playback of the source.
void setVolume (float volume)
 Set the base volume level for the source.
void stop (float fadeOutTime=-1.f)
 Stop playback of the source.
Callbacks

void onParameterValueChange (SFXParameter parameter)
 Called when a parameter attached to the source changes value.
void onStatusChange (SFXStatus newStatus)
 Called when the playback status of the source changes.

Public Attributes

Sound

SFXDescription description
 The playback configuration that determines the initial sound properties and setup.
string statusCallback
 Name of function to call when the status of the source changes.

Detailed Description

Playback controller for a sound source.

All sound playback is driven by SFXSources. Each such source represents an independent playback controller that directly or indirectly affects sound output.

While this class itself is instantiable, such an instance will not by itself emit any sound. This is the responsibility of its subclasses. Note, however, that none of these subclasses must be instantiated directly but must instead be instantiated indirectly through the SFX interface.

Play-Once Sources

Often, a sound source need only exist for the duration of the sound it is playing. In this case so-called "play-once" sources simplify the bookkeeping involved by leaving the deletion of sources that have expired their playtime to the sound system.

Play-once sources can be created in either of two ways:

See also:
sfxPlayOnce
sfxDeleteWhenStopped

Source Hierarchies

Source are arranged into playback hierarchies where a parent source will scale some of the properties of its children and also hand on any play(), pause(), and stop() commands to them. This allows to easily group sounds into logical units that can then be operated on as a whole.

An example of this is the segregation of sounds according to their use in the game. Volume levels of background music, in-game sound effects, and character voices will usually be controlled independently and putting their sounds into different hierarchies allows to achieve that easily.

The source properties that are scaled by parent values are:

This means that if a parent has a volume of 0.5, the child will play at half the effective volume it would otherwise have.

Additionally, parents affect the playback state of their children:

Each source maintains a state that is wants to be in which may differ from the state that is enforced on it by its parent. If a parent changes its states in a way that allows a child to move into its desired state, the child will do so.

For logically grouping sources, instantiate the SFXSource class directly and make other sources children to it. A source thus instantiated will not effect any real sound output on its own but will influence the sound output of its direct and indirect children.

Note:
Be aware that the property values used to scale child property values are the effective values. For example, the value used to scale the volume of a child is the effective volume of the parent, i.e. the volume after fades, distance attenuation, etc. has been applied.
See also:
SFXDescription::sourceGroup

Volume Attenuation

During its lifetime, the volume of a source will be continually updated. This update process always progresses in a fixed set of steps to compute the final effective volume of the source based on the base volume level that was either assigned from the SFXDescription associated with the source (SFXDescription::volume) or manually set by the user. The process of finding a source's final effective volume is called "volume attenuation". The steps involved in attenuating a source's volume are (in order):

Fading
If the source currently has a fade-effect applied, the volume is interpolated along the currently active fade curve.
Modulation
If the source is part of a hierarchy, it's volume is scaled according to the effective volume of its parent.
Distance Attenuation
If the source is a 3D sound source, then the volume is interpolated according to the distance model in effect and current listener position and orientation (see 3D Audio).
See also:
SFXDescription::volume
SFXDescription::is3d

Volume Fades

To ease-in and ease-out playback of a sound, fade effects may be applied to sources. A fade will either go from zero volume to full effective volume (fade-in) or from full effective volume to zero volume (fade-out).

Fading is coupled to the play(), pause(), and stop() methods as well as to loop iterations when SFXDescription::fadeLoops is true for the source. play() and the start of a loop iteration will trigger a fade-in whereas pause(), stop() and the end of loop iterations will trigger fade-outs.

For looping sources, if SFXDescription::fadeLoops is false, only the initial play() will trigger a fade-in and no further fading will be applied to loop iterations.

By default, the fade durations will be governed by the SFXDescription::fadeInTime and SFXDescription::fadeOutTime properties of the SFXDescription attached to the source. However, these may be overridden on a per-source basis by setting fade times explicitly with setFadeTimes(). Additionally, the set values may be overridden for individual play(), pause(), and stop() calls by supplying appropriate fadeInTime/fadeOutTime parameters.

By default, volume will interpolate linearly during fades. However, custom interpolation curves can be assigned through the SFXDescription::fadeInEase and SFXDescription::fadeOutTime properties.

See also:
SFXDescription::fadeInTime
SFXDescription::fadeOutTime
SFXDescription::fadeInEase
SFXDescription::fadeOutEase
SFXDescription::fadeLoops

Sound Cones

See also:
SFXDescription::coneInsideAngle
SFXDescription::coneOutsideAngle
SFXDescription::coneOutsideVolume

Doppler Effect

See also:
sfxGetDopplerFactor
sfxSetDopplerFactor
SFXAmbience::dopplerFactor

Playback Markers

Playback markers allow to attach notification triggers to specific playback positions. Once the play cursor crosses a position for which a marker is defined, the onMarkerPassed callback will be triggered on the SFXSource thus allowing to couple script logic to .

Be aware that the precision with which marker callbacks are triggered are bound by global source update frequency. Thus there may be a delay between the play cursor actually passing a marker position and the callback being triggered.


Member Function Documentation

void SFXSource::addMarker ( String  name,
float  pos 
)

Add a notification marker called name at pos seconds of playback.

Parameters:
name Symbolic name for the marker that will be passed to the onMarkerPassed() callback.
pos Playback position in seconds when the notification should trigger. Note that this is a soft limit and there may be a delay between the play cursor actually passing the position and the callback being triggered.
Note:
For looped sounds, the marker will trigger on each iteration.
Example:
// Create a new source.
$source = sfxCreateSource( AudioMusicLoop2D, "art/sound/backgroundMusic" );

// Assign a class to the source.
$source.class = "BackgroundMusic";

// Add a playback marker at one minute into playback.
$source.addMarker( "first", 60 );

// Define the callback function.  This function will be called when the playback position passes the one minute mark.
function BackgroundMusic::onMarkerPassed( %this, %markerName )
{
   if( %markerName $= "first" )
      echo( "Playback has passed the 60 seconds mark." );
}

// Play the sound.
$source.play();
void SFXSource::addParameter ( SFXParameter  parameter  ) 

Attach parameter to the source,.

Once attached, the source will react to value changes of the given parameter. Attaching a parameter will also trigger an initial read-out of the parameter's current value.

Parameters:
parameter The parameter to attach to the source.
float SFXSource::getAttenuatedVolume (  ) 

Get the final effective volume level of the source.

This method returns the volume level as it is after source group volume modulation, fades, and distance-based volume attenuation have been applied to the base volume level.

Returns:
The effective volume of the source.

Volume Attenuation

float SFXSource::getFadeInTime (  ) 

Get the fade-in time set on the source.

This will initially be SFXDescription::fadeInTime.

Returns:
The fade-in time set on the source in seconds.
See also:
SFXDescription::fadeInTime

Volume Fades

float SFXSource::getFadeOutTime (  ) 

Get the fade-out time set on the source.

This will initially be SFXDescription::fadeOutTime.

Returns:
The fade-out time set on the source in seconds.
See also:
SFXDescription::fadeOutTime

Volume Fades

SFXParameter SFXSource::getParameter ( int  index  ) 

Get the parameter at the given index.

Parameters:
index Index of the parameter to fetch. Must be 0<=index<=getParameterCount().
Returns:
The parameter at the given index or null if index is out of range.
Example:
// Print the name ofo each parameter attached to %source.
%numParams = %source.getParameterCount();
for( %i = 0; %i < %numParams; %i ++ )
   echo( %source.getParameter( %i ).getParameterName() );
See also:
getParameterCount
int SFXSource::getParameterCount (  ) 

Get the number of SFXParameters that are attached to the source.

Returns:
The number of parameters attached to the source.
Example:
// Print the name ofo each parameter attached to %source.
%numParams = %source.getParameterCount();
for( %i = 0; %i < %numParams; %i ++ )
   echo( %source.getParameter( %i ).getParameterName() );
See also:
getParameter
addParameter
float SFXSource::getPitch (  ) 

Get the pitch scale of the source.

Pitch determines the playback speed of the source (default: 1).

Returns:
The current pitch scale factor of the source.
See also:
setPitch
SFXDescription::pitch
SFXStatus SFXSource::getStatus (  ) 

Get the current playback status.

Returns:
Te current playback status
float SFXSource::getVolume (  ) 

Get the current base volume level of the source.

This is not the final effective volume that the source is playing at but rather the starting volume level before source group modulation, fades, or distance-based volume attenuation are applied.

Returns:
The current base volume level.
See also:
setVolume
SFXDescription::volume

Volume Attenuation

bool SFXSource::isPaused (  ) 

Test whether the source is currently paused.

Returns:
True if the source is in paused state, false otherwise.
See also:
pause
getStatus
SFXStatus
bool SFXSource::isPlaying (  ) 

Test whether the source is currently playing.

Returns:
True if the source is in playing state, false otherwise.
See also:
play
getStatus
SFXStatus
bool SFXSource::isStopped (  ) 

Test whether the source is currently stopped.

Returns:
True if the source is in stopped state, false otherwise.
See also:
stop
getStatus
SFXStatus
void SFXSource::onParameterValueChange ( SFXParameter  parameter  ) 

Called when a parameter attached to the source changes value.

This callback will be triggered before the value change has actually been applied to the source.

Parameters:
parameter The parameter that has changed value.
Note:
This is also triggered when the parameter is first attached to the source.
void SFXSource::onStatusChange ( SFXStatus  newStatus  ) 

Called when the playback status of the source changes.

Parameters:
newStatus The new playback status.
void SFXSource::pause ( float  fadeOutTime = -1.f  ) 

Pause playback of the source.

Parameters:
fadeOutTime Seconds for the sound to fade down to zero volume. If -1, the SFXDescription::fadeOutTime set in the source's associated description is used. Pass 0 to disable a fade-out effect that may be configured on the description. Be aware that if a fade-out effect is used, the source will not immediately to paused state but will rather remain in playing state until the fade-out time has expired..
void SFXSource::removeParameter ( SFXParameter  parameter  ) 

Detach parameter from the source.

Once detached, the source will no longer react to value changes of the given parameter.

If the parameter is not attached to the source, the method will do nothing.

Parameters:
parameter The parameter to detach from the source.
void SFXSource::setCone ( float  innerAngle,
float  outerAngle,
float  outsideVolume 
)

Set up the 3D volume cone for the source.

Parameters:
innerAngle Angle of the inner sound cone in degrees (SFXDescription::coneInsideAngle). Must be 0<=innerAngle<=360.
outerAngle Angle of the outer sound cone in degrees (SFXDescription::coneOutsideAngle). Must be 0<=outerAngle<=360.
outsideVolume Volume scale factor outside of outer cone (SFXDescription::coneOutsideVolume). Must be 0<=outsideVolume<=1.
Note:
This method has no effect on the source if the source is not 3D.
void SFXSource::setFadeTimes ( float  fadeInTime,
float  fadeOutTime 
)

Set the fade time parameters of the source.

Parameters:
fadeInTime The new fade-in time in seconds.
fadeOutTime The new fade-out time in seconds.
See also:
SFXDescription::fadeInTime
SFXDescription::fadeOutTime

Volume Fades

void SFXSource::setPitch ( float  pitch  ) 

Set the pitch scale of the source.

Pitch determines the playback speed of the source (default: 1).

Parameters:
pitch The new pitch scale factor.
See also:
getPitch
SFXDescription::pitch
void SFXSource::setTransform ( Point3F  position,
Point3F  direction 
)

Start playback of the source.

Set the position and orientation of the source's 3D sound.

Parameters:
position The new position in world space.
direction The forward vector.

Set the position of the source's 3D sound.

Parameters:
position The new position in world space.
Note:
This method has no effect if the source is not a 3D source.

If the sound data for the source has not yet been fully loaded, there will be a delay after calling play and playback will start after the data has become available.

Parameters:
fadeInTime Seconds for the sound to reach full volume. If -1, the SFXDescription::fadeInTime set in the source's associated description is used. Pass 0 to disable a fade-in effect that may be configured on the description.
void SFXSource::setVolume ( float  volume  ) 

Set the base volume level for the source.

This volume will be the starting point for source group volume modulation, fades, and distance-based volume attenuation.

Parameters:
volume The new base volume level for the source. Must be 0>=volume<=1.
See also:
getVolume

Volume Attenuation

void SFXSource::stop ( float  fadeOutTime = -1.f  ) 

Stop playback of the source.

Parameters:
fadeOutTime Seconds for the sound to fade down to zero volume. If -1, the SFXDescription::fadeOutTime set in the source's associated description is used. Pass 0 to disable a fade-out effect that may be configured on the description. Be aware that if a fade-out effect is used, the source will not immediately transtion to stopped state but will rather remain in playing state until the fade-out time has expired.

Member Data Documentation

The playback configuration that determines the initial sound properties and setup.

Any SFXSource must have an associated SFXDescription.

Name of function to call when the status of the source changes.

The source that had its status changed is passed as the first argument to the function and the new status of the source is passed as the second argument.



Copyright © GarageGames, LLC. All Rights Reserved.