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 import android.compat.annotation.UnsupportedAppUsage; 20 import android.os.Build; 21 22 /** 23 * The AudioGain describes a gain controller. Gain controllers are exposed by 24 * audio ports when the gain is configurable at this port's input or output. 25 * Gain values are expressed in millibels. 26 * A gain controller has the following attributes: 27 * - mode: defines modes of operation or features 28 * MODE_JOINT: all channel gains are controlled simultaneously 29 * MODE_CHANNELS: each channel gain is controlled individually 30 * MODE_RAMP: ramps can be applied when gain changes 31 * - channel mask: indicates for which channels the gain can be controlled 32 * - min value: minimum gain value in millibel 33 * - max value: maximum gain value in millibel 34 * - default value: gain value after reset in millibel 35 * - step value: granularity of gain control in millibel 36 * - min ramp duration: minimum ramp duration in milliseconds 37 * - max ramp duration: maximum ramp duration in milliseconds 38 * 39 * This object is always created by the framework and read only by applications. 40 * Applications get a list of AudioGainDescriptors from AudioPortDescriptor.gains() and can build a 41 * valid gain configuration from AudioGain.buildConfig() 42 * @hide 43 */ 44 public class AudioGain { 45 46 /** 47 * Bit of AudioGain.mode() field indicating that 48 * all channel gains are controlled simultaneously 49 */ 50 public static final int MODE_JOINT = 1; 51 /** 52 * Bit of AudioGain.mode() field indicating that 53 * each channel gain is controlled individually 54 */ 55 public static final int MODE_CHANNELS = 2; 56 /** 57 * Bit of AudioGain.mode() field indicating that 58 * ramps can be applied when gain changes. The type of ramp (linear, log etc...) is 59 * implementation specific. 60 */ 61 public static final int MODE_RAMP = 4; 62 63 private final int mIndex; 64 private final int mMode; 65 private final int mChannelMask; 66 private final int mMinValue; 67 private final int mMaxValue; 68 private final int mDefaultValue; 69 private final int mStepValue; 70 private final int mRampDurationMinMs; 71 private final int mRampDurationMaxMs; 72 73 // The channel mask passed to the constructor is as specified in AudioFormat 74 // (e.g. AudioFormat.CHANNEL_OUT_STEREO) 75 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) AudioGain(int index, int mode, int channelMask, int minValue, int maxValue, int defaultValue, int stepValue, int rampDurationMinMs, int rampDurationMaxMs)76 AudioGain(int index, int mode, int channelMask, 77 int minValue, int maxValue, int defaultValue, int stepValue, 78 int rampDurationMinMs, int rampDurationMaxMs) { 79 mIndex = index; 80 mMode = mode; 81 mChannelMask = channelMask; 82 mMinValue = minValue; 83 mMaxValue = maxValue; 84 mDefaultValue = defaultValue; 85 mStepValue = stepValue; 86 mRampDurationMinMs = rampDurationMinMs; 87 mRampDurationMaxMs = rampDurationMaxMs; 88 } 89 90 /** 91 * Bit field indicating supported modes of operation 92 */ mode()93 public int mode() { 94 return mMode; 95 } 96 97 /** 98 * Indicates for which channels the gain can be controlled 99 * (e.g. AudioFormat.CHANNEL_OUT_STEREO) 100 */ channelMask()101 public int channelMask() { 102 return mChannelMask; 103 } 104 105 /** 106 * Minimum gain value in millibel 107 */ minValue()108 public int minValue() { 109 return mMinValue; 110 } 111 112 /** 113 * Maximum gain value in millibel 114 */ maxValue()115 public int maxValue() { 116 return mMaxValue; 117 } 118 119 /** 120 * Default gain value in millibel 121 */ defaultValue()122 public int defaultValue() { 123 return mDefaultValue; 124 } 125 126 /** 127 * Granularity of gain control in millibel 128 */ stepValue()129 public int stepValue() { 130 return mStepValue; 131 } 132 133 /** 134 * Minimum ramp duration in milliseconds 135 * 0 if MODE_RAMP not set 136 */ rampDurationMinMs()137 public int rampDurationMinMs() { 138 return mRampDurationMinMs; 139 } 140 141 /** 142 * Maximum ramp duration in milliseconds 143 * 0 if MODE_RAMP not set 144 */ rampDurationMaxMs()145 public int rampDurationMaxMs() { 146 return mRampDurationMaxMs; 147 } 148 149 /** 150 * Build a valid gain configuration for this gain controller for use by 151 * AudioPortDescriptor.setGain() 152 * @param mode: desired mode of operation 153 * @param channelMask: channels of which the gain should be modified. 154 * @param values: gain values for each channels. 155 * @param rampDurationMs: ramp duration if mode MODE_RAMP is set. 156 * ignored if MODE_JOINT. 157 */ buildConfig(int mode, int channelMask, int[] values, int rampDurationMs)158 public AudioGainConfig buildConfig(int mode, int channelMask, 159 int[] values, int rampDurationMs) { 160 //TODO: check params here 161 return new AudioGainConfig(mIndex, this, mode, channelMask, values, rampDurationMs); 162 } 163 } 164