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) AudioGain(int index, int mode, int channelMask, int minValue, int maxValue, int defaultValue, int stepValue, int rampDurationMinMs, int rampDurationMaxMs)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 */ mode()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 */ channelMask()97 public int channelMask() { 98 return mChannelMask; 99 } 100 101 /** 102 * Minimum gain value in millibel 103 */ minValue()104 public int minValue() { 105 return mMinValue; 106 } 107 108 /** 109 * Maximum gain value in millibel 110 */ maxValue()111 public int maxValue() { 112 return mMaxValue; 113 } 114 115 /** 116 * Default gain value in millibel 117 */ defaultValue()118 public int defaultValue() { 119 return mDefaultValue; 120 } 121 122 /** 123 * Granularity of gain control in millibel 124 */ stepValue()125 public int stepValue() { 126 return mStepValue; 127 } 128 129 /** 130 * Minimum ramp duration in milliseconds 131 * 0 if MODE_RAMP not set 132 */ rampDurationMinMs()133 public int rampDurationMinMs() { 134 return mRampDurationMinMs; 135 } 136 137 /** 138 * Maximum ramp duration in milliseconds 139 * 0 if MODE_RAMP not set 140 */ rampDurationMaxMs()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 */ buildConfig(int mode, int channelMask, int[] values, int rampDurationMs)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