Home | History | Annotate | Download | only in media 
      1 /*
      2  * Copyright (C) 2014 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.media;
     18 
     19 /**
     20  * The AudioGain describes a gain controller. Gain controllers are exposed by
     21  * audio ports when the gain is configurable at this port's input or output.
     22  * Gain values are expressed in millibels.
     23  * A gain controller has the following attributes:
     24  * - mode: defines modes of operation or features
     25  *    MODE_JOINT: all channel gains are controlled simultaneously
     26  *    MODE_CHANNELS: each channel gain is controlled individually
     27  *    MODE_RAMP: ramps can be applied when gain changes
     28  * - channel mask: indicates for which channels the gain can be controlled
     29  * - min value: minimum gain value in millibel
     30  * - max value: maximum gain value in millibel
     31  * - default value: gain value after reset in millibel
     32  * - step value: granularity of gain control in millibel
     33  * - min ramp duration: minimum ramp duration in milliseconds
     34  * - max ramp duration: maximum ramp duration in milliseconds
     35  *
     36  * This object is always created by the framework and read only by applications.
     37  * Applications get a list of AudioGainDescriptors from AudioPortDescriptor.gains() and can build a
     38  * valid gain configuration from AudioGain.buildConfig()
     39  * @hide
     40  */
     41 public class AudioGain {
     42 
     43     /**
     44      * Bit of AudioGain.mode() field indicating that
     45      * all channel gains are controlled simultaneously
     46      */
     47     public static final int MODE_JOINT = 1;
     48     /**
     49      * Bit of AudioGain.mode() field indicating that
     50      * each channel gain is controlled individually
     51      */
     52     public static final int MODE_CHANNELS = 2;
     53     /**
     54      * Bit of AudioGain.mode() field indicating that
     55      * ramps can be applied when gain changes. The type of ramp (linear, log etc...) is
     56      * implementation specific.
     57      */
     58     public static final int MODE_RAMP = 4;
     59 
     60     private final int mIndex;
     61     private final int mMode;
     62     private final int mChannelMask;
     63     private final int mMinValue;
     64     private final int mMaxValue;
     65     private final int mDefaultValue;
     66     private final int mStepValue;
     67     private final int mRampDurationMinMs;
     68     private final int mRampDurationMaxMs;
     69 
     70     // The channel mask passed to the constructor is as specified in AudioFormat
     71     // (e.g. AudioFormat.CHANNEL_OUT_STEREO)
     72     AudioGain(int index, int mode, int channelMask,
     73                         int minValue, int maxValue, int defaultValue, int stepValue,
     74                         int rampDurationMinMs, int rampDurationMaxMs) {
     75         mIndex = index;
     76         mMode = mode;
     77         mChannelMask = channelMask;
     78         mMinValue = minValue;
     79         mMaxValue = maxValue;
     80         mDefaultValue = defaultValue;
     81         mStepValue = stepValue;
     82         mRampDurationMinMs = rampDurationMinMs;
     83         mRampDurationMaxMs = rampDurationMaxMs;
     84     }
     85 
     86     /**
     87      * Bit field indicating supported modes of operation
     88      */
     89     public int mode() {
     90         return mMode;
     91     }
     92 
     93     /**
     94      * Indicates for which channels the gain can be controlled
     95      * (e.g. AudioFormat.CHANNEL_OUT_STEREO)
     96      */
     97     public int channelMask() {
     98         return mChannelMask;
     99     }
    100 
    101     /**
    102      * Minimum gain value in millibel
    103      */
    104     public int minValue() {
    105         return mMinValue;
    106     }
    107 
    108     /**
    109      * Maximum gain value in millibel
    110      */
    111     public int maxValue() {
    112         return mMaxValue;
    113     }
    114 
    115     /**
    116      * Default gain value in millibel
    117      */
    118     public int defaultValue() {
    119         return mDefaultValue;
    120     }
    121 
    122     /**
    123      * Granularity of gain control in millibel
    124      */
    125     public int stepValue() {
    126         return mStepValue;
    127     }
    128 
    129     /**
    130      * Minimum ramp duration in milliseconds
    131      * 0 if MODE_RAMP not set
    132      */
    133     public int rampDurationMinMs() {
    134         return mRampDurationMinMs;
    135     }
    136 
    137     /**
    138      * Maximum ramp duration in milliseconds
    139      * 0 if MODE_RAMP not set
    140      */
    141     public int rampDurationMaxMs() {
    142         return mRampDurationMaxMs;
    143     }
    144 
    145     /**
    146      * Build a valid gain configuration for this gain controller for use by
    147      * AudioPortDescriptor.setGain()
    148      * @param mode: desired mode of operation
    149      * @param channelMask: channels of which the gain should be modified.
    150      * @param values: gain values for each channels.
    151      * @param rampDurationMs: ramp duration if mode MODE_RAMP is set.
    152      * ignored if MODE_JOINT.
    153      */
    154     public AudioGainConfig buildConfig(int mode, int channelMask,
    155                                        int[] values, int rampDurationMs) {
    156         //TODO: check params here
    157         return new AudioGainConfig(mIndex, this, mode, channelMask, values, rampDurationMs);
    158     }
    159 }
    160