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:
- Level Silence Threshold. After
setLevel(0.0)
, getDB
returns the value for which smaller values are not usefully
distinguishable from silence.
Calling setDB
with values equal to or less than this silence
threshold causes getLevel
to return a value of 0.0.
- Level Maximum Threshold. After
setLevel(1.0)
, getDB
returns the value for which larger values are not useful.
Calling setDB
with values equal to or greater than this
threshold causes getLevel
to return a value of 1.0.
- The decibel interface is not limited to the thresholds
described by the level interface.
For example, if you call
setDB
with a value that is greater than the
maximum level threshold and then immediately call
getDB
, getDB
returns the gain
that was returned by the setDB
, not the value that
would be returned if you called setLevel(1.0)
and then
called getDB
.
- Both measures increase gain monotonically with increasing
measure values.
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
-
addGainChangeListener(GainChangeListener)
- Register for gain change update events.
-
getDB()
- Get the current gain set for this object in dB.
-
getLevel()
- Get the current gain set for this
object as a value between 0.0 and 1.0
-
getMute()
- Get the mute state of the signal associated with this
GainControl
.
-
removeGainChangeListener(GainChangeListener)
- Remove interest in gain change update events.
-
setDB(float)
- Set the gain in decibels.
-
setLevel(float)
- Set the gain using a floating point scale
with values between 0.0 and 1.0.
-
setMute(boolean)
- Mute or unmute the signal associated with this
GainControl
.
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.
getMute
public abstract boolean getMute()
- Get the mute state of the signal associated with this
GainControl
.
- Returns:
- The mute state.
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.
getDB
public abstract float getDB()
- Get the current gain set for this object in dB.
- Returns:
- The gain in dB.
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.
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).
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.
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