All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface javax.media.GainControl

public interface GainControl
extends Control
GainControl is an interface for manipulating audio signal gain.

Gain and Gain Measures

Gain is a multiplicative value applied to an audio signal that modifies the amplitude of the signal. This interface allows the gain to be specified in either decibels or using a floating point value that varies between 0.0 and 1.0.

Specifying Gain in Decibels

The decibel scale is valid over all float values. A gain of 0.0 dB implies that the audio signal is neither amplified nor attenuated. Positive values amplify the audio signal, negative values attenuate the audio signal. The relationship between a linear gain multiplier and the gain specified in decibels is:

value = pow(10.0, gainDB/20.0)

Specifying Gain in the Level Scale

The level scale ranges from 0.0 to 1.0, where 0.0 represents a gain that is virtually indistinguishable from silence and 1.0 represents the value that is, in some sense, the maximum gain. In other words, 1.0 represents the highest gain value that produces "useful" results. The mapping for producing a linear multiplicative value is implementation dependent.

Decibel and Level Interactions

The dB and level scales are representations of the same gain value. Calling setLevel will affect subsequent getDB invocations. Level and dB are interrelated in the following ways:

Defaults

Gain defaults to a value of 0.0 dB. The corresponding level is implementation dependent. Note that for some implementations, the default level might change on a per-instance basis.

Mute

Muting is independent of the gain. If mute is true, no audio signal is produced by this object; if mute is false an audio signal is produced and the gain is applied to the signal.

Gain Change Events

When the state of the GainControl changes, a GainChangeEvent is posted. This event is delivered through an object that implements GainChangeListener and has been registered as a listener with the GainControl using addGainChangeListener.

Version:
1.33, 97/08/23
See Also:
GainChangeEvent, GainChangeListener, Control

Method Index

 o addGainChangeListener(GainChangeListener)
Register for gain change update events.
 o getDB()
Get the current gain set for this object in dB.
 o getLevel()
Get the current gain set for this object as a value between 0.0 and 1.0
 o getMute()
Get the mute state of the signal associated with this GainControl.
 o removeGainChangeListener(GainChangeListener)
Remove interest in gain change update events.
 o setDB(float)
Set the gain in decibels.
 o setLevel(float)
Set the gain using a floating point scale with values between 0.0 and 1.0.
 o setMute(boolean)
Mute or unmute the signal associated with this GainControl.

Methods

 o setMute
 public abstract void setMute(boolean mute)
Mute or unmute the signal associated with this GainControl. Calling setMute(true) on an object that is already muted is ignored, as is calling setMute(false) on an object that is not currently muted. Going from a muted to an unmuted state doesn't effect the gain.

Parameters:
mute - Specify true to mute the signal, false to unmute the signal.
 o getMute
 public abstract boolean getMute()
Get the mute state of the signal associated with this GainControl.

Returns:
The mute state.
 o setDB
 public abstract float setDB(float gain)
Set the gain in decibels. Setting the gain to 0.0 (the default) implies that the audio signal is neither amplified nor attenuated. Positive values amplify the audio signal and negative values attenuate the signal.

Parameters:
gain - The new gain in dB.
Returns:
The gain that was actually set.
 o getDB
 public abstract float getDB()
Get the current gain set for this object in dB.

Returns:
The gain in dB.
 o setLevel
 public abstract float setLevel(float level)
Set the gain using a floating point scale with values between 0.0 and 1.0. 0.0 is silence; 1.0 is the loudest useful level that this GainControl supports.

Parameters:
level - The new gain value specified in the level scale.
Returns:
The level that was actually set.
 o getLevel
 public abstract float getLevel()
Get the current gain set for this object as a value between 0.0 and 1.0

Returns:
The gain in the level scale (0.0-1.0).
 o addGainChangeListener
 public abstract void addGainChangeListener(GainChangeListener listener)
Register for gain change update events. A GainChangeEvent is posted when the state of the GainControl changes.

Parameters:
listener - The object to deliver events to.
 o removeGainChangeListener
 public abstract void removeGainChangeListener(GainChangeListener listener)
Remove interest in gain change update events.

Parameters:
listener - The object that has been receiving events.

All Packages  Class Hierarchy  This Package  Previous  Next  Index