Main   Class List   Namespace List   Wiki

SFXParameter Class Reference
[Sound]

A sound channel value that can be bound to multiple sound sources. More...

Inheritance diagram for SFXParameter:
Inheritance graph
[legend]

List of all members.

Public Member Functions

String getParameterName ()
 Get the name of the parameter.
void reset ()
 Reset the parameter's value to its default.
Callbacks

void onUpdate ()
 Called when the sound system triggers an update on the parameter.

Public Attributes

Sound

SFXChannel channel
 Channel that the parameter controls.
float defaultValue
 Value to which the parameter is initially set.
string description
 Textual description of the parameter.
Point2F range
 Permitted range for value.
float value
 Current value of the audio parameter.

Detailed Description

A sound channel value that can be bound to multiple sound sources.

Parameters are special objects that isolate a specific property that sound sources can have and allows to bind this isolated instance to multiple sound sources such that when the value of the parameter changes, all sources bound to the parameter will have their respective property changed.

Parameters are identified and referenced by their internalName. This means that the SFXDescription::parameters and SFXTrack::parameters fields should contain the internalNames of the SFXParameter objects which should be attached to the SFXSources when they are created. No two SFXParameters should have the same internalName.

All SFXParameter instances are automatically made children of the SFXParameterGroup.

Note:
To simply control the volume and/or pitch levels of a group of sounds, it is easier and more efficient to use a sound source group rather than SFXParameters (see Source Hierarchies). Simply create a SFXSource object representing the group, assign SFXDescription::sourceGroup of the sounds appropriately, and then set the volume and/or pitch level of the group to modulate the respective properties of all children.

Parameter Updates

Parameters are periodically allowed to update their own values. This makes it possible to attach custom logic to a parameter and have individual parameters synchronize their values autonomously. Use the onUpdate() callback to attach script code to a parameter update.

Example:
new SFXParameter( EngineRPMLevel )
{
   // Set the name by which this parameter is identified.
   internalName = "EngineRPMLevel";

   // Let this parameter control the pitch of attached sources to simulate engine RPM ramping up and down.
   channel = "Pitch";

   // Start out with unmodified pitch.
   defaultValue = 1;

   // Add a texture description of what this parameter does.
   description = "Engine RPM Level";
};

// Create a description that automatically attaches the engine RPM parameter.
singleton SFXDescription( EngineRPMSound : AudioLoop2D )
{
   parameters[ 0 ] = "EngineRPMLevel";
};

// Create sound sources for the engine.
sfxCreateSource( EngineRPMSound, "art/sound/engine/enginePrimary" );
sfxCreateSource( EngineRPMSound, "art/sound/engine/engineSecondary" );

// Setting the parameter value will now affect the pitch level of both sound sources.
EngineRPMLevel.value = 0.5;
EngineRPMLevel.value = 1.5;

Interactive Audio


Member Function Documentation

String SFXParameter::getParameterName (  ) 

Get the name of the parameter.

Returns:
The paramete name.
void SFXParameter::onUpdate (  ) 

Called when the sound system triggers an update on the parameter.

This occurs periodically during system operation.

void SFXParameter::reset (  ) 

Reset the parameter's value to its default.

See also:
SFXParameter::defaultValue

Member Data Documentation

Channel that the parameter controls.

This controls which property of the sources it is attached to the parameter controls.

Value to which the parameter is initially set.

When the parameter is first added to the system, value will be set to defaultValue.

Textual description of the parameter.

Primarily for use in the Audio Parameters dialog of the editor to allow for easier identification of parameters.

Permitted range for value.

Minimum and maximum allowed value for the parameter. Both inclusive.

For all but the User0-3 channels, this property is automatically set up by SFXParameter.

Current value of the audio parameter.

All attached sources are notified when this value changes.



Copyright © GarageGames, LLC. All Rights Reserved.