javax.media.GainControl Maven / Gradle / Ivy
/**
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example,
this file and any files generated from it may be used to generate other documentation,
such as a unified set of documents of API signatures for a platform
that includes technologies expressed as Java APIs.
This file may also be used to produce "compilation stubs,"
which allow applications to be compiled and validated for such platforms.
By contrast, no permission is given for you to incorporate this file,
in whole or in part, in an implementation of a Java specification.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.
In the event of a discrepency between this work and the JSR 927 specification,
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/
package javax.media;
/**
* 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.
*
* @see GainChangeEvent
* @see GainChangeListener
* @see Control
* @version 1.34, 05/10/18
*/
public interface GainControl extends Control
{
/**
* 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.
*
* @param mute Specify true to mute the signal, false to unmute the signal.
*/
public void setMute(boolean mute);
/**
* Get the mute state of the signal associated with this
* GainControl.
*
* @return The mute state.
*
*/
public boolean getMute();
/**
* 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.
*
* @param gain The new gain in dB.
* @return The gain that was actually set.
*/
public float setDB(float gain);
/**
* Get the current gain set for this object in dB.
* @return The gain in dB.
*/
public float getDB();
/**
* 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.
*
* @param level The new gain value specified in the level scale.
* @return The level that was actually set.
*/
public float setLevel(float level);
/**
* Get the current gain set for this
* object as a value between 0.0 and 1.0
*
* @return The gain in the level scale (0.0-1.0).
*/
public float getLevel();
/**
* Register for gain change update events.
* A GainChangeEvent is posted when the state
* of the GainControl changes.
*
* @param listener The object to deliver events to.
*/
public void addGainChangeListener(GainChangeListener listener);
/**
* Remove interest in gain change update events.
*
* No action is performed if the specified listener is not registered.
*
* @param listener The object that has been receiving events.
*/
public void removeGainChangeListener(GainChangeListener listener);
}