/*
 * @(#)GainControl.java	1.2 02/08/21
 *
 * Copyright (c) 1996-2002 Sun Microsystems, Inc.  All rights reserved.
 */

package javax.media;

/**
 * <code>GainControl</code> is an interface for manipulating audio signal
 * gain.
 *
 * <h3>Gain and Gain Measures</h3>
 * 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.
 *
 * <h4>Specifying Gain in Decibels</h4>
 * The decibel scale is valid over all <code>float</code>
 * 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:
 * <p>
 *
 *<CENTER><CODE> value = pow(10.0, gainDB/20.0) </CODE></CENTER>
 *
 *<h4>Specifying Gain in the Level Scale</h4>
 * 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.
 *
 * <h4>Decibel and Level Interactions</h4>
 * The dB and level scales are representations
 * of the same gain value. Calling <code>setLevel</code> 
 * will affect subsequent <code>getDB</code> invocations.
 * Level and dB are interrelated in the following ways:
 *
 * <ul>
 * <li>Level Silence Threshold. After <code>setLevel(0.0)</code>, <code>getDB</code> 
 * returns the value for which smaller values are not usefully 
 * distinguishable from silence.
 * Calling <code>setDB</code> with values equal to or less than this silence
 * threshold causes <code>getLevel</code> to return a value of 0.0.
 *
 * <li>Level Maximum Threshold. After <code>setLevel(1.0)</code>, <code>getDB</code>
 * returns the value for which  larger values are not useful. 
 * Calling <code>setDB</code> with values equal to or greater than this
 * threshold causes <code>getLevel</code> to return a value of 1.0.
 *
 * <li>The decibel interface is not limited to the thresholds
 * described by the level interface.
 * For example, if you call <code>setDB</code> with a value that is greater than the
 * maximum level threshold and then immediately call 
 * <code>getDB</code>,  <code>getDB</code>  returns the gain 
 * that was returned by the <code>setDB</code>,   <i>not</i> the value that
 * would be returned if you called <code>setLevel(1.0)</code> and then
 * called <code>getDB</code>.
 * 
 * <li>Both measures increase gain monotonically with increasing
 *  measure values.
 *  </ul>
 *
 * <h4>Defaults</h4>
 * 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.
 *
 * <h3>Mute</h3>
 * Muting is independent of the gain. If mute is <CODE>true</CODE>,
 * no audio signal is produced by this object; if mute is <CODE>false</CODE>
 * an audio signal is produced and the gain is applied to the
 * signal.
 *
 * <h3>Gain Change Events</h3>
 * When the state of the <code>GainControl</code> changes, a
 * <code>GainChangeEvent</code> is posted.
 * This event is delivered through an object
 * that implements <code>GainChangeListener</code> and has been registered as a listener
 * with the <code>GainControl</code> using <code>addGainChangeListener</code>.

 * @see GainChangeEvent
 * @see GainChangeListener
 * @see Control
 * @version 1.2, 02/08/21
*/

public interface GainControl extends Control {
    
    /**
     * Mute or unmute the signal associated with this <code>GainControl</code>.
     *
     * Calling <code>setMute(true)</code> on
     * an object that is already muted is ignored, as is calling
     * <code>setMute(false)</code> on an object that is not currently muted.
     * Going from a muted to an unmuted state doesn't effect the
     * gain.
     *
     * @param mute Specify <CODE>true</CODE> to mute the signal, <CODE>false</CODE> to unmute the signal.
    */
    public void setMute(boolean mute);

    /**
     * Get the mute state of the signal associated with this 
     * <code>GainControl</code>.
     *
     * @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 <code>GainControl</code> 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 <code>GainChangeEvent</code> is posted when the state
     * of the <code>GainControl</code> changes.
     *
     * @param listener The object to deliver events to.
    */
    public void addGainChangeListener(GainChangeListener listener);

    /**
     * Remove interest in gain change update events.
     *
     * @param listener The object that has been receiving events.
    */
    public void removeGainChangeListener(GainChangeListener listener);
    
}